Skip to Content

Prerequisites

Everything you need before making your first API request to the SMS Pro Gateway.

View Markdown (.md)

Before integrating with the SMS Pro platform, ensure you have gathered the required credentials, understand telecommunication formatting rules, and have a testing environment configured.


1. Account & Credential Requirements

To call any SMS Pro endpoint, you will need:

  • An Active SMS Pro Account: Registered on the SMS Pro Platform (see Create an Account).
  • Developer Mode Enabled: Your organization must toggle Developer Mode in account settings to reveal the developer tools and API management interfaces.
  • An API Key: Either a Sandbox test key (sk_test_...) for zero-cost simulated testing, or a Live production key (sk_live_...) with required scopes such as sms:send.

Sandbox Key Recommended First

Start with an sk_test_ key. Those requests use the same API, do not charge the wallet, and do not send to a handset.


2. Telecommunication Formatting Standards

SMS messaging over telco networks relies on specific international formatting, automatic number normalization, and character encoding rules:

Flexible Phone Number Formats & Automatic Normalization

SMS Pro accepts local and international forms and cleans them on ingest. You do not need a separate normalizer in your application.

The platform natively accepts all of the following formats:

Format TypeInput ExampleGateway NormalizationStatusNotes
Local Format (with leading 0)0241234567233241234567SupportedStandard 10-digit Ghana local mobile number. The leading 0 is replaced with 233.
International (without +)233241234567233241234567Supported12-digit international format without leading plus.
Standard E.164 (with +)+233241234567233241234567SupportedStandard E.164 with country dial code.
National (9-digit)241234567233241234567Supported9-digit format omitting leading zero. The gateway prepends 233.
Formatted / Punctuation+233 (24) 123-4567 or 024-123-4567233241234567SupportedSpaces, dashes, and parentheses are automatically stripped before processing.

Automatic Ingestion Cleaning & Deduplication

Whether you pass 0241234567, 233241234567, or +233241234567, SMS Pro normalizes all inputs to the carrier-standard routing MSISDN (233241234567). In batch and campaign dispatches, duplicate representations of the same phone number in a single request are automatically consolidated.

Invalid Number Rejections

A recipient number is rejected with HTTP 422 and INVALID_PHONE_NUMBER or DESTINATION_COUNTRY_NOT_SUPPORTED in these cases:

  • Incorrect Digit Count: Local Ghana numbers starting with 0 that do not contain exactly 10 digits (e.g. 024123 or 024123456789).
  • Unsupported Destination: Submitting phone numbers for countries not currently activated in your organization's routing profile (e.g. attempting to send to a UK +44 number when your account is configured for Ghana-only routing).
  • Empty / Non-numeric Inputs: Strings containing no numeric digits.

GSM-7 vs. UCS-2 Encoding & Segment Limits

Carrier billing and SMS delivery rely on message segmentation:

  • Standard GSM-7 Encoding: Plain alphanumeric characters, punctuation, and standard symbols support up to 160 characters in a single SMS segment. Messages longer than 160 characters are automatically split into concatenated multi-part segments of 153 characters each (due to concatenation headers).
  • UCS-2 (Unicode) Encoding: If your message contains emojis, accents, or non-Latin scripts (Arabic, Chinese, Cyrillic), the carrier forces UCS-2 encoding. This restricts a single segment to 70 characters (or 67 characters per concatenated segment).

Emoji Character Pitfall

Adding a single emoji (such as 👋 or 🚀) converts the entire message payload from GSM-7 to UCS-2, reducing the segment threshold from 160 to 70 characters and increasing your billing unit consumption.

Sender ID Guidelines

The senderId parameter designates the alphanumeric brand name displayed in the recipient's SMS inbox:

  • Maximum length: 11 alphanumeric characters (A-Z, a-z, 0-9).
  • Special characters, spaces, and punctuation are restricted by telecom regulators.
  • In production, telecom regulators (such as Ghana's NCA) mandate business registration and whitelisting before your custom Sender ID can route over live carrier channels.
  • In the Sandbox environment, you can use any test Sender ID (e.g. SMSPRO, MYAPP).

3. Tooling & Development Environment

SMS Pro communicates over standard HTTPS with JSON request bodies. The runtimes and utilities listed below are the ones used for the interactive code samples throughout this documentation:

Documentation Sample Runtimes

  • cURL: Command-line HTTP requests (native on macOS, Linux, and Windows PowerShell).
  • TypeScript / Node.js: v18.0+ (supports native global fetch and crypto.randomUUID()).
  • Python: v3.9+ with requests or httpx.
  • PHP: v8.0+ with native cURL or GuzzleHttp.
  • Java: v17+ with native java.net.http.HttpClient or OkHttp.

Interactive API Testing Utilities

  • Postman / Insomnia / Bruno: For visual exploration, saving request collections, and inspecting response headers.
  • HTTPie: Fast, human-friendly CLI HTTP client.

Using Other Languages or Frameworks?

Because SMS Pro is a standard RESTful API over HTTPS, you can connect from any programming language or environment supporting TLS 1.2+ (including C# / .NET, Go, Ruby, Rust, Flutter, Dart, Swift, or Kotlin).

If your team requires code walkthroughs, sample boilerplates, or integration assistance in an environment not covered in these guides, please reach out to our Developer Support Team or open a ticket in your Customer Console.


Next Step

Now that you understand the platform requirements and telecom conventions, follow the registration walkthrough in Create an Account.

On this page