API
API

Send SMS

API for sending SMS messages to international numbers (e.g., OTP verification codes, marketing, notifications).

📌 Request Method

  • URL: api.moymobile.com/sms
  • Protocol: HTTP / HTTPS
  • Method: POST
  • Authentication: Basic Auth (Base64 encoded account credentials)

📮 Request Headers

Header Name Type Required Description
Authorization string Yes Basic authentication, format:Basic Base64(AccountID:ApiKey)
Content-Type string Yes Fixed value: application/json
Authorization Example Explanation

Assume:

  • AccountID: 1910159943521189888
  • ApiKey: 12f76074-f686-4b23-8b15-8714651b815c

Concatenate string:

1910159943521189888:12f76074-f686-4b23-8b15-8714651b815c

Base64 encode:

MTkxMDE1OTk0MzUyMTE4OTg4ODoxMmY3NjA3NC1mNjg2LTRiMjMtOGIxNS04NzE0NjUxYjgxNWM=

Final header:

Authorization: Basic MTkxMDE1OTk0MzUyMTE4OTg4ODoxMmY3NjA3NC1mNjg2LTRiMjMtOGIxNS04NzE0NjUxYjgxNWM=

🧾 Request Body Parameters

Parameter Type Required Description
from string ✅ Sender identifier (Sender ID)
to array of objects ✅ Recipient list, each item with phoneNumber (E.164 format) and optional variables
templateId string ✅ Template ID for templated SMS
reference string ❌ Custom parameter, max 400 characters, returned as-is in status report

Each to item contains:

Field Type Required Description
phoneNumber string ✅ Recipient number in E.164 format (e.g., +14155550000)
other variables string / number ❌ According to your template, you can pass variables (e.g., code)

For example, if your template is:
Your verification code is: ${code}
then you must provide a code variable in each to item.
If your template has no variables, you only need to pass phoneNumber.

Request Body Example
{
  "from": "moy",
  "to": [
    {
      "phoneNumber": "+14155550000",
      "code": 2234
    }
  ],
  "reference": "reference",
  "templateId": "101"
}

📌 International SMS is charged per submission.

📌 E.164 format means '+' + country code + phone number, e.g., +14155550000.

📌 Template ID is assigned in your account; template variables (like code) will replace placeholders.

📌 SMS content length is calculated after variable substitution:
GSM 7bit encoding counts 160 characters per SMS; over 160 characters split by 153 chars per segment.
Unicode encoding counts 70 characters per SMS; over 70 split by 67 chars per segment.

💻 Request Example

Java OkHttp 
OkHttpClient client = new OkHttpClient().newBuilder().build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n" +
    "    \"from\": \"moy\",\n" +
    "    \"to\": [\n" +
    "        {\n" +
    "            \"phoneNumber\": \"+14155550000\",\n" +
    "            \"code\": 2234\n" +
    "        }\n" +
    "    ],\n" +
    "    \"reference\": \"reference\",\n" +
    "    \"templateId\": \"101\"\n" +
    "}");
Request request = new Request.Builder()
  .url("https://api.moymobile.com/sms")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "Basic MTkxMDE1OTk0MzUyMTE4OTg4ODoxMmY3NjA3NC1mLTRiMjMtOGIxNS04NzE0NjUxYjgxNWM=")
  .build();
Response response = client.newCall(request).execute();

✅ Successful Response Example（200 OK）

{
  "code": 0,
  "message": "Success",
  "data": [
    {
      "messageId": "1933000268379787264",
      "accountId": "1910159943521189888",
      "to": "+14155550000",
      "from": "1",
      "status": "PENDING",
      "fee": 0.0051,
      "parts": 1,
      "submittedAt": "2025-06-12T03:15:52.047Z",
      "currency": "USD"
    }
  ]
}

📦 Response Fields Explanation（data array）

Field Type Description
messageId string Unique SMS ID (globally unique)
accountId string Account ID
to string Recipient number
from string Sender identifier
status string Current status, e.g., PENDING
fee number SMS cost in currency units
currency string Currency code (e.g., USD)
parts number Number of segments (long SMS may be split)
submittedAt string Submission time (ISO 8601 format)

❌ Error Response Example (Authentication Failure)

{
  "code": 1001,
  "message": "Missing or invalid authorization header.",
  "data": null
}

📘 Status Code Descriptions

These status codes are business-level response codes, returned in the JSON body.
Standard HTTP status codes are still used at the HTTP layer (e.g., 200, 400, 401, 500),
and these codes should be interpreted along with the HTTP status.

Code Description
0 Request processed successfully
1001 Missing or invalid Authorization header
1002 Invalid Basic Authentication format
1003 Missing or invalid account identifier
1004 Account is not activated
1005 Request IP address is restricted (not in the allowed whitelist)
1006 Empty or malformed request body
1007 Required parameters are missing
1008 Invalid messageType parameter
1009 Invalid phone number format (must be E.164)
1010 Pricing is unavailable for the current country or region
1011 Insufficient account balance
1012 Template does not exist, is not approved, or has expired
1013 Missing required variable(s) for the given phone recipient
1000 Other or unspecified server-side error

ℹ️ These codes are included in the response body under the code field,
while the HTTP status code will typically be 200 OK if the request was technically successful,
or 4xx/5xx if a transport-level error occurs.

ON THIS Page