{ "info": { "_postman_id": "0cedc08e-91b2-4da4-a2c2-fd11f99ba21f", "name": "BulkSMSOnline SMS API", "description": "Send bulk SMS, transactional alerts, OTPs, and notifications worldwide using our REST and HTTP APIs.\n\n## Key Features\n\n- Global SMS delivery to 200+ countries\n- REST API (JSON) and HTTP API (GET/POST parameters)\n- Real-time delivery reports via callbacks\n- Webhook support for status updates\n- Simple API key authentication\n- Scalable for marketing campaigns, alerts, and 2FA\n \n\n## Base URLs\n\n- **REST API:** `https://api.bulksmsonline.co/rest/api/v1`\n- **HTTP API:** `https://api.bulksmsonline.co/smsapi`\n \n\n## Authentication\n\nBulkSMSOnline APIs use account credentials and service tokens depending on the API type. Keep credentials secure and never expose them in frontend JavaScript, public repositories, or mobile app bundles.\n\n- **HTTP API:** Uses username and password parameters in the API request.\n- **REST API:** Generate a token first, then include the token with each SMS request.\n- **SMPP API**: Uses SMPP username, password, host, port, bind type, and IP whitelist approval.\n- **WEBHOOKS:** Use your configured callback URL to receive delivery status updates from BulkSMSOnline.", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", "_exporter_id": "55303559", "_collection_link": "https://go.postman.co/collection/55303559-0cedc08e-91b2-4da4-a2c2-fd11f99ba21f?source=collection_link" }, "item": [ { "name": "HTTP SMS API", "item": [ { "name": "HTTP SMS Endpoint", "request": { "method": "GET", "header": [], "url": { "raw": "https://api.bulksmsonline.co/smsapi?username=xxxx&password=yyyyy&type=t&to=0000000000&source=sender&message=YourText", "protocol": "https", "host": [ "api", "bulksmsonline", "co" ], "path": [ "smsapi" ], "query": [ { "key": "username", "value": "xxxx", "description": "Your account username." }, { "key": "password", "value": "yyyyy", "description": "Your account password. Note: If the password contains special characters, spaces, symbols, or reserved URL characters, it must be URL-encoded before being sent via the API." }, { "key": "type", "value": "t", "description": "Defines the SMS message type.\nt —-- Plain text message for English/Latin content. The message must be URL-encoded and should use GSM 03.38 character encoding.\nu —-- Unicode message for languages such as Arabic, Chinese, or other non-Latin scripts." }, { "key": "to", "value": "0000000000", "description": "One or more recipient phone numbers, separated by commas. Maximum 30 numbers per request." }, { "key": "source", "value": "sender", "description": "The sender ID/name that will appear as the SMS sender.\nNumeric sender ID: maximum 18 digits.\nAlphanumeric sender ID: maximum 11 characters.\nAdditional restrictions may apply depending on the SMSC or destination network." }, { "key": "message", "value": "YourText", "description": "The SMS message body. For plain text messages, such as English or Latin-based content, the message must be URL-encoded and should use GSM 03.38 character encoding.\nFor Unicode messages, such as Arabic, Chinese, Korean, or other non-Latin languages, our API supports both UTF-16BE text and normal Unicode text. You can send the message normally without converting it to UTF-16BE, as long as the text is properly URL-encoded when sent through a URL/API request." }, { "key": "scheduled", "value": "2020-01-13T12:49:00", "description": "Schedule the SMS to be sent at a future date and time.\nThe date/time must be provided in ISO 8601 format: yyyy-MM-ddTHH:mm:ss\nThe value must be URL-encoded when sent via API.\nThe scheduled time must be based on the UTC-04:00 timezone.", "type": "text", "disabled": true } ] } }, "response": [] }, { "name": "HTTP SMS Endpoint (post)", "request": { "method": "POST", "header": [], "url": { "raw": "https://api.bulksmsonline.co/smsapi?username=xxxx&password=yyyyy&type=t&to=0000000000&source=sender&message=YourText", "protocol": "https", "host": [ "api", "bulksmsonline", "co" ], "path": [ "smsapi" ], "query": [ { "key": "username", "value": "xxxx", "description": "Your account username." }, { "key": "password", "value": "yyyyy", "description": "Your account password. Note: If the password contains special characters, spaces, symbols, or reserved URL characters, it must be URL-encoded before being sent via the API." }, { "key": "type", "value": "t", "description": "Defines the SMS message type.\nt —-- Plain text message for English/Latin content. The message must be URL-encoded and should use GSM 03.38 character encoding.\nu —-- Unicode message for languages such as Arabic, Chinese, or other non-Latin scripts." }, { "key": "to", "value": "0000000000", "description": "One or more recipient phone numbers, separated by commas. Maximum 30 numbers per request." }, { "key": "source", "value": "sender", "description": "The sender ID/name that will appear as the SMS sender.\nNumeric sender ID: maximum 18 digits.\nAlphanumeric sender ID: maximum 11 characters.\nAdditional restrictions may apply depending on the SMSC or destination network." }, { "key": "message", "value": "YourText", "description": "\tThe SMS message body.\nFor plain text messages, such as English or Latin-based content, the message must be URL-encoded and should use GSM 03.38 character encoding.\nFor Unicode messages, such as Arabic, Chinese, Korean, or other non-Latin languages, our API supports both UTF-16BE text and normal Unicode text. You can send the message normally without converting it to UTF-16BE, as long as the text is properly URL-encoded when sent through a URL/API request." }, { "key": "scheduled", "value": "2020-01-13T12:49:00", "description": "Schedule the SMS to be sent at a future date and time.\nThe date/time must be provided in ISO 8601 format: yyyy-MM-ddTHH:mm:ss\nThe value must be URL-encoded when sent via API.\nThe scheduled time must be based on the UTC-04:00 timezone.", "type": "text", "disabled": true } ] } }, "response": [] } ], "description": "The HTTP API is the fastest way to send SMS messages using a simple GET or POST request. It is useful for legacy systems, direct server-side integrations, and lightweight notification workflows.\n\n| Presence | Parameter | Description |\n| --- | --- | --- |\n| Mandatory | `username` | Your account username. |\n| Mandatory | `password` | Your account password.Note: `If the password contains special characters, spaces, symbols, or reserved URL characters, it must be URL-encoded before being sent via the API.` |\n| Mandatory | `type` | Defines the SMS message type.

\\- t —-- Plain text message for English/Latin content. The message must be URL-encoded and should use GSM 03.38 character encoding.

\\- u —-- Unicode message for languages such as Arabic, Chinese, or other non-Latin scripts. |\n| Mandatory | `to` | One or more recipient phone numbers, separated by commas. Maximum **30 numbers** per request. |\n| Mandatory | `source` | The sender ID/name that will appear as the SMS sender.

\\- Numeric sender ID: maximum **18 digits**.

\\- Alphanumeric sender ID: maximum **11 characters**.

\\- Additional restrictions may apply depending on the SMSC or destination network. |\n| Mandatory | `message` | The SMS message body.

\\- For plain text messages, such as English or Latin-based content, the message must be URL-encoded and should use GSM 03.38 character encoding.

\\- For Unicode messages, such as Arabic, Chinese, Korean, or other non-Latin languages, our API supports both UTF-16BE text and normal Unicode text. You can send the message normally without converting it to UTF-16BE, as long as the text is properly URL-encoded when sent through a URL/API request. |\n| Optional | `scheduled` | Schedule the SMS to be sent at a future date and time.

\\- The date/time must be provided in ISO 8601 format: `yyyy-MM-ddTHH:mm:ss`

\\- The value must be URL-encoded when sent via API.

\\- The scheduled time must be based on the **UTC-04:00** timezone.

Example: `scheduled=2020-01-13T12:49:00` |\n\n| Response / Error Code | Meaning | Description | Recommended Action |\n| --- | --- | --- | --- |\n| OK| | Message accepted | The SMS request was submitted successfully. The API response includes a unique message ID. | Save the returned message ID for delivery tracking, logs, and support reference. |\n| `E0002` | Invalid request | The request URL is invalid, or one or more required parameters are missing, empty, or sent in the wrong format. | Check the request URL and make sure all required parameters are included correctly. |\n| `E0003` | Invalid username or password | The username or password parameter is missing, incorrect, or not formatted properly. | Verify the API credentials. If the password contains special characters, URL-encode it before sending the request. |\n| `E0004` | Invalid message type | The `type` parameter is invalid. Supported values include `t` for plain text SMS and `u` for Unicode SMS. | Send a valid message type according to the message encoding you are using. |\n| `E0005` | Invalid message body | The SMS message text is empty, invalid, or not encoded correctly. | Make sure the message body is not empty. Plain text messages should be URL-encoded. Unicode messages should be encoded in UTF-16BE. |\n| `E0006` | Invalid recipient number | The `to` parameter contains an invalid mobile number or unsupported number format. | Use international MSISDN format without spaces or invalid characters. For multiple recipients, separate numbers with commas. |\n| `E0007` | Invalid sender ID | The `source` parameter does not match the allowed sender ID format. Numeric sender IDs can contain up to 15 digits, while alphanumeric sender IDs can contain up to 11 characters. | Check the sender ID format and confirm that the sender is allowed for the destination country, route, or SMSC. |\n| `E0008` | Authentication failed | The API credentials are incorrect, inactive, or not allowed to use the requested API service. | Verify the account username, password, account status, and API access permissions. |\n| `E0010` | Internal server error | The request could not be processed because of a temporary system-side issue. | Retry after a short time. If the issue continues, contact support with the request URL, timestamp, and account username. |\n| `E0022` | Insufficient balance | The account does not have enough SMS credit to submit the message. | Top up the account balance and retry the request. |\n| `E0033` / `HTTP 429` | Rate limit exceeded | The API sending rate limit has been exceeded. The maximum allowed rate is **30 SMS submissions per second**. | Reduce the sending speed, queue messages on your side, and retry after a short delay. |\n| `E0044` | Mobile network not supported | The destination number belongs to a mobile network that is not currently supported by the selected route or service. | Check the destination network and contact support if you need coverage for this operator or country. |" }, { "name": "Account Balance API", "item": [ { "name": "Balance Endpoint", "request": { "method": "GET", "header": [], "url": { "raw": "https://api.bulksmsonline.co/balance?username=XXXX&password=YYYYY", "protocol": "https", "host": [ "api", "bulksmsonline", "co" ], "path": [ "balance" ], "query": [ { "key": "username", "value": "XXXX", "description": "Your BulkSMSOnline account username." }, { "key": "password", "value": "YYYYY", "description": "Your BulkSMSOnline account password." } ] } }, "response": [] }, { "name": "Balance Endpoint (post)", "request": { "method": "POST", "header": [], "url": { "raw": "https://api.bulksmsonline.co/balance?username=XXXX&password=YYYYY", "protocol": "https", "host": [ "api", "bulksmsonline", "co" ], "path": [ "balance" ], "query": [ { "key": "username", "value": "XXXX", "description": "Your BulkSMSOnline account username." }, { "key": "password", "value": "YYYYY", "description": "Your BulkSMSOnline account password." } ] } }, "response": [] } ], "description": "Use the Account Balance API to check the available SMS balance for your account. The endpoint supports both **GET** and **POST**, but POST is recommended for better credential privacy.\n\n| Parameter | Required | Method | Description |\n| --- | --- | --- | --- |\n| `username` | Yes | GET / POST | Your BulkSMSOnline account username. |\n| `password` | Yes | GET / POST | Your BulkSMSOnline account password. |" }, { "name": "REST SMS API", "item": [ { "name": "Generate REST API Token", "item": [], "description": "GET [https://api.bulksmsonline.co/rest/api/v1/sms/gettoken/username/{YourUsername}/password/{YourPassword}](https://api.bulksmsonline.co/rest/api/v1/sms/gettoken/username/%7BYourUsername%7D/password/%7BYourPassword%7DEndFragment)\n\nGenerate a temporary REST API token using your BulkSMSOnline username and password. Use this token when calling the REST API by passing it in the `token` HTTP header.\n\n| Parameter | Location | Required | Description |\n| --- | --- | --- | --- |\n| `username` | Path | Yes | Your account username or registered mobile number. |\n| `password` | Path | Yes | Your account password. |\n\n#### Successful Token Response\n\nHTTP 200 Response application/json\n\n``` json\n{\n \"token\": \"YOUR_GENERATED_REST_TOKEN\"\n}\n\n ```\n\n### Generate Token HTTP Status Codes\n\nThe token endpoint may return the following HTTP status codes.\n\n| HTTP Status | Meaning | Description |\n| --- | --- | --- |\n| `200 OK` | Success | Returns the newly generated REST API token. |\n| `401 Unauthorized` | Unauthorized | The provided username or password is incorrect. |\n| `402 Payment Required` | Payment Required | The account has zero balance or the account/service has expired. |\n| `402 Payment Required` | Forbidden / Invalid Action | The request contains an invalid action or the account is not allowed to perform the action. |\n| `404 Not Found` | Invalid Path | The requested endpoint path is invalid. |\n| `405 Method Not Allowed` | Wrong Method | The endpoint was called using an unsupported HTTP method. |\n| `500 Internal Server Error` | Server Error | An unexpected server-side error occurred. |\n| `503 Service Unavailable` | Service Unavailable | The service is temporarily unavailable. |" }, { "name": "Send SMS", "protocolProfileBehavior": { "disabledSystemHeaders": { "accept": true } }, "request": { "auth": { "type": "noauth" }, "method": "POST", "header": [ { "key": "Accept", "value": "application/json", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" }, { "key": "token", "value": "YOUR_GENERATED_REST_TOKEN", "type": "text" } ], "body": { "mode": "raw", "raw": "{\r\n \"from\": \"YourBrand\",\r\n \"to\": [\r\n \"1234567890\"\r\n ],\r\n \"type\": \"Text\",\r\n \"content\": \"Your SMS message\",\r\n \"sendDateTime\": null\r\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://api.bulksmsonline.co/rest/api/v1/sms/send/", "protocol": "https", "host": [ "api", "bulksmsonline", "co" ], "path": [ "rest", "api", "v1", "sms", "send", "" ] }, "description": "Use this endpoint to send one SMS or a bulk SMS request through the REST API. The request body must be sent as JSON, and the generated REST API token must be passed using the `token` HTTP header. Each request supports up to **30 destination numbers** in the `to` array.\n\nStartFragment\n\n#### SMS Request Object Parameters\n\n| Field | Type | Required | Nullable | Description |\n| --- | --- | --- | --- | --- |\n| `from` | string | No | Yes | Sender ID or originator name. If omitted or set to `null`, the system may use the default originator available for the account or route. |\n| `to` | array of strings | Yes | Yes | Destination mobile numbers in international MSISDN format, such as `1234567890` or `+1234567890`. For bulk sending, include multiple destination numbers in the `to` array. A single REST SMS request can include up to **30 destination numbers**. |\n| `type` | string enum | Yes | No | SMS message type. Supported values: `Text`, `UniCode`. |\n| `content` | string | Yes | Yes | The SMS message body to be delivered to the recipient. The API accepts plain text messages such as English letters, numbers, and standard symbols. It also accepts Unicode messages such as Arabic, Chinese, Korean, and other non-Latin languages, either sent normally as URL-encoded Unicode text or as UTF-16BE text when required. |\n| `sendDateTime` | string/date-time | No | Yes | Schedule the SMS to be sent at a future date and time. The value must be provided in ISO 8601 format: `yyyy-MM-ddTHH:mm:ss`. The scheduled time must be based on the **UTC-04:00 timezone**. Use `null` or omit the field for immediate sending.
Example: `\"sendDateTime\": \"2020-01-13T12:49:00\"` |\n\n### REST API Formats and Rules\n\n| Item | Rule |\n| --- | --- |\n| Protocol | HTTPS is supported and recommended for all REST API requests. |\n| Request format | Requests must be sent as valid JSON using `application/json`. |\n| Response format | Responses are returned as JSON unless otherwise specified. |\n| Invalid JSON | Requests with invalid JSON may be rejected with a bad request response. |\n| Null values | Nullable fields may be omitted or sent as `null` where supported. |\n| MSISDN format | Mobile numbers should be sent in international format, with or without a leading `+`, and without a leading `00`. |\n| Number normalization | Spaces, dashes, and brackets in destination numbers are ignored by the API. Returned MSISDNs are normalized without `+` or `00`. |\n\n### Rate Limits\n\nThe REST SMS API supports sending up to **30 SMS messages per second**. This limit is calculated by the number of destination messages, not only by the number of API requests.\n\n**Example:** If one REST request contains 30 destination numbers in the `to` array, it counts as 30 SMS messages and uses the full 30 SMS/second allowance for that second.\n\n| Limit Type | Limit | Details |\n| --- | --- | --- |\n| REST API send rate | **30 SMS / second** | The API can process up to 30 destination SMS messages per second. If you send to multiple recipients in one request, each recipient counts as one SMS message. |\n| Recipients per request | **Maximum 30 numbers** | The `to` array can include up to 30 destination mobile numbers in a single REST SMS request. |\n| Large campaigns | Split into batches | For campaigns larger than 30 recipients, split the campaign into multiple REST requests while keeping the sending speed within 30 SMS per second. |\n\n### Send SMS Response Codes\n\nThe send SMS endpoint may return a response containing a `code` value. The following response codes are used to indicate whether the SMS request was accepted or rejected.\n\n| HTTP Status | Code | Description | Recommended Developer Action |\n| --- | --- | --- | --- |\n| `200` | `Success` | SMS request was accepted successfully. | No action required. Store the API response for tracking and audit purposes. |\n| `400` | `Bad Request` | Invalid parameters were provided in the request. | Check the JSON body, required fields, destination numbers, sender ID, and message type. |\n| `401` | `Unauthorized` | The REST token is missing, invalid, or expired. | Generate a new token and send it using the `token` HTTP header. |\n| `404` | `Not Found` | The endpoint path is invalid. | Confirm that you are using the correct versioned endpoint URL. |\n| `405` | `-` | The HTTP method is not allowed. | Use `POST` for sending SMS. |\n| `500` | `-` | Internal server error. | Retry later. If the issue continues, contact support with the request details. |\n| `503` | `-` | Service unavailable. | Retry after a short delay. |\n\n**Important:** Token generation uses your account username and password, but sending SMS through the REST API requires the generated token only. Do not expose your account password in client-side JavaScript, mobile apps, public repositories, or browser-based integrations." }, "response": [] } ], "description": "Use the REST SMS API to send SMS messages from your application over HTTPS using JSON requests and structured JSON responses. The API supports single SMS sending, bulk sending to multiple recipients, and scheduled SMS delivery using a generated REST API token." }, { "name": "SMPP API", "item": [ { "name": "SMPP Connection Details", "item": [], "description": "| Setting | Value | Notes |\n| --- | --- | --- |\n| Host | `smpp.bulksmsonline.com` | Production SMPP host. |\n| Port | `8889` | SMPP connection port. |\n| Username / System ID | Provided by support | Your SMPP account username, also commonly used as the SMPP system ID. |\n| Password | Provided by support | Your SMPP account password. |\n| Bind modes | Transmitter / Receiver / Transceiver | Use transmitter mode for sending, receiver mode for delivery reports, or transceiver mode for both sending and receiving on the same connection. |\n| Maximum binds | **2 binds by default** | Each SMPP account includes 2 default binds. Contact your account manager if you need more concurrent connections. |\n| IP whitelist | **Required** | Your sending server IP address must be added to the firewall whitelist before you can connect to the SMPP server. |\n| SMSC timezone | `UTC` | BulkSMSOnline SMSC uses UTC for SMPP processing and timing. |" }, { "name": "Supported SMPP PDUs", "item": [], "description": "The SMPP interface supports the standard PDU operations required for binding, message submission, delivery report receiving, link checking, message query, replacement, cancellation, and graceful session closure.\n\n| PDU | Direction | Purpose |\n| --- | --- | --- |\n| `bind_transmitter` / `bind_transmitter_resp` | Client ↔ SMSC | Bind as a transmitter to submit outbound SMS messages. |\n| `bind_receiver` / `bind_receiver_resp` | Client ↔ SMSC | Bind as a receiver to receive delivery reports or inbound SMPP messages. |\n| `bind_transceiver` / `bind_transceiver_resp` | Client ↔ SMSC | Bind as a transceiver to send messages and receive reports on the same connection. |\n| `submit_sm` / `submit_sm_resp` | Client ↔ SMSC | Submit an outbound SMS message and receive the submission response. |\n| `data_sm` / `data_sm_resp` | Client ↔ SMSC | Submit or receive message data using the SMPP data_sm operation. |\n| `deliver_sm` / `deliver_sm_resp` | SMSC ↔ Client | Receive delivery reports or mobile-originated messages, depending on route support. |\n| `enquire_link` / `enquire_link_resp` | Client ↔ SMSC | Keep the SMPP session alive and verify that the connection is still active. |\n| `unbind` / `unbind_resp` | Client ↔ SMSC | Close the SMPP session gracefully. |\n| `generic_nack` | Client ↔ SMSC | Generic negative acknowledgement for invalid or unsupported PDU handling. |\n| `query_sm` / `query_sm_resp` | Client ↔ SMSC | Query the status of a previously submitted message where supported. |\n| `cancel_sm` / `cancel_sm_resp` | Client ↔ SMSC | Request cancellation of a scheduled or pending message where supported. |\n| `replace_sm` / `replace_sm_resp` | Client ↔ SMSC | Request replacement of a previously submitted message where supported. |" }, { "name": "Throughput, Window Size & Keepalive", "item": [], "description": "**Default Throughput**\n\nThe default SMPP throughput is**10 MT messages per second per bind**. Higher throughput may be available by request and depends on account approval, route capacity, and operator limits.\n\n- **Maximum Available Throughput**\n \n\nSMPP can support high-volume sending up to**60 messages per second**where enabled for the account and supported by the destination route.\n\n- **Window Size**\n \n\nRecommended default window size is**5 open requests**. This means up to 5 submit requests may be waiting for responses at the same time.\n\n- **Enquire Link**\n \n\nSend `enquire_link` every**60 seconds**to keep the SMPP connection alive and detect broken sessions.\n\n**Throttling note:** SMPP throughput is calculated by MT messages per second. If the allowed sending rate is exceeded, the SMSC may return a throttling error such as `0x00000058`." }, { "name": "Sender ID, TON/NPI & MSISDN Format", "item": [], "description": "SMPP source and destination addressing should be configured correctly using the appropriate TON and NPI values for the sender and recipient format used by your SMPP client.\n\n| Item | Limit / Format | Notes |\n| --- | --- | --- |\n| Alphanumeric sender ID | **Maximum 11 characters** | Use for brand names or approved alphanumeric originators where supported by the route and destination country. |\n| Numeric sender / MSISDN sender | **Maximum 18 digits** | Numeric sender IDs should follow MSISDN-style numbering rules. |\n| Destination MSISDN | `CC + NDC + SN` | Use international number format: country code, national destination code, and subscriber number. |\n| Country Code | `CC` | The international country code, such as `1`, `44`, or `62`. |\n| National Destination Code | `NDC` | The network or area portion of the mobile number. |\n| Subscriber Number | `SN` | The final subscriber number portion of the MSISDN. |" }, { "name": "Submitting Messages", "item": [], "description": "Messages can be submitted using `submit_sm` or `data_sm`. Message content may be sent using either the `short_message` field or the `message_payload` optional parameter, depending on your SMPP client implementation and message type.\n\n| Submission Item | Supported Value | Details |\n| --- | --- | --- |\n| Submission PDU | `submit_sm` or `data_sm` | Used to submit outbound SMS messages through the SMPP bind. |\n| Message content field | `short_message` or `message_payload` | Use the field supported by your SMPP client and message encoding requirements. |\n| Standard GSM message size | Up to **140 bytes** | Message size depends on network and encoding. For GSM SMS, the message byte limit is commonly 140 bytes. |\n| Concatenated SMS | Supported using UDH | Long SMS messages may be sent using User Data Header segmentation. UDH bytes are included in the total message size limit. |" }, { "name": "Submit Responses", "item": [], "description": "A successful submit response returns command status `0x00000000` and a non-empty message reference. A failed submit response returns an SMPP command status error code or vendor-specific error code.\n\n| Response Type | Command Status | Meaning | Developer Action |\n| --- | --- | --- | --- |\n| Positive submit response | `0x00000000` | No error. Message was accepted by the SMSC. | Store the returned message reference for delivery report matching. |\n| Negative submit response | Non-zero error code | The message was rejected or could not be processed. | Check the error code, request fields, sender ID, destination number, and throughput. |" }, { "name": "Delivery Reports", "item": [], "description": "Delivery reports are returned through `deliver_sm`. To receive delivery reports, connect using receiver or transceiver mode, depending on your SMPP client design.\n\n| DLR Status | Description | Meaning |\n| --- | --- | --- |\n| `DELIVRD` | Message delivered to handset. | The SMS was successfully delivered to the recipient device. |\n| `FAILED` | Message could not be delivered. | The message failed before successful delivery. |\n| `EXPIRED` | Message validity period expired. | The SMS expired before it could be delivered. |\n| `UNDELIV` | Message is undeliverable. | The destination could not receive the message. |\n| `REJECTD` | Message rejected. | The message was rejected by the route, SMSC, operator, or filtering layer. |" }, { "name": "SMPP Error Codes", "item": [], "description": "The following SMPP command status values may be returned in SMPP responses. A status value of `0x00000000` means no error. Non-zero values indicate that the SMPP request was rejected or could not be processed.\n\n| Hex Value | Decimal | Description |\n| --- | --- | --- |\n| `0x00000000` | 0 | No Error |\n| `0x00000001` | 1 | Message length is invalid |\n| `0x00000002` | 2 | Command length is invalid |\n| `0x00000003` | 3 | Invalid Command ID |\n| `0x00000004` | 4 | Incorrect BIND Status for given command |\n| `0x00000005` | 5 | ESME already in bound state |\n| `0x00000006` | 6 | Invalid Priority Flag |\n| `0x00000007` | 7 | Invalid Registered Delivery Flag |\n| `0x00000008` | 8 | System Error |\n| `0x00000009` | \\- | Reserved |\n| `0x0000000A` | 10 | Invalid Source Address |\n| `0x0000000B` | 11 | Invalid Destination Address |\n| `0x0000000C` | 12 | Message ID is invalid |\n| `0x0000000D` | 13 | Bind Failed |\n| `0x0000000E` | 14 | Invalid Password |\n| `0x0000000F` | 15 | Invalid System ID |\n| `0x00000010` | 16 | Reserved |\n| `0x00000011` | 17 | Cancel SM Failed |\n| `0x00000012` | \\- | Reserved |\n| `0x00000013` | 19 | Replace SM Failed |\n| `0x00000014` | 20 | Message Queue Full |\n| `0x00000015` | 21 | Invalid Service Type |\n| `0x00000016` | \\- | Reserved through `0x00000032` |\n| `0x00000033` | 51 | Invalid number of destinations |\n| `0x00000034` | 52 | Invalid Distribution List name |\n| `0x00000035` | 53 | Reserved through `0x0000003F` |\n| `0x00000040` | 64 | Destination flag is invalid for `submit_multi` |\n| `0x00000041` | \\- | Reserved |\n| `0x00000042` | 66 | Invalid submit with replace request; `submit_sm` with `replace_if_present_flag` set |\n| `0x00000043` | 67 | Invalid `esm_class` field data |\n| `0x00000044` | 68 | Cannot submit to distribution list |\n| `0x00000045` | 69 | `submit_sm` or `submit_multi` failed |\n| `0x00000046` | \\- | Reserved through `0x00000047` |\n| `0x00000048` | 72 | Invalid Source Address TON |\n| `0x00000049` | 73 | Invalid Source Address NPI |\n| `0x00000050` | 80 | Invalid Destination Address TON |\n| `0x00000051` | 81 | Invalid Destination Address NPI |\n| `0x00000052` | \\- | Reserved |\n| `0x00000053` | 83 | Invalid `system_type` field |\n| `0x00000054` | 84 | Invalid `replace_if_present` flag |\n| `0x00000055` | 85 | Invalid number of messages |\n| `0x00000056` | \\- | Reserved through `0x00000057` |\n| `0x00000058` | 88 | Throttling error; ESME has exceeded allowed message limits |\n| `0x00000059` | 89 | Reserved through `0x00000060` |\n| `0x00000061` | 97 | Invalid Scheduled Delivery Time |\n| `0x00000062` | 98 | Invalid message validity period / expiry time |\n| `0x00000063` | 99 | Predefined Message Invalid or Not Found |\n| `0x00000064` | 100 | ESME Receiver Temporary Application Error Code |\n| `0x00000065` | 101 | ESME Receiver Permanent Application Error Code |\n| `0x00000066` | 102 | ESME Receiver Reject Message Error Code |\n| `0x00000067` | 103 | `query_sm` request failed |\n| `0x00000068` | 104 | Reserved through `0x000000BF` |\n| `0x000000C0` | 192 | Error in the optional part of the PDU body |\n| `0x000000C1` | 193 | Optional parameter not allowed |\n| `0x000000C2` | 194 | Invalid parameter length |\n| `0x000000C3` | 195 | Expected optional parameter missing |\n| `0x000000C4` | 196 | Invalid optional parameter value |\n| `0x000000C5` - `0x000000FD` | \\- | Reserved |\n| `0x000000FE` | 245 | Delivery Failure, used for `data_sm_resp` |\n| `0x000000FF` | 255 | Unknown Error |\n| `0x00000100` - `0x000003FF` | \\- | Reserved for SMPP extension |" } ], "description": "The SMPP API is designed for customers who need direct protocol-level SMS connectivity, low latency, higher throughput, delivery report handling, and more control over message submission. SMPP is commonly used by telecom providers, aggregators, platforms, and high-volume senders that need a persistent SMS connection instead of request-based HTTP APIs.\n\n**Access required:** SMPP access is available for approved customers. To connect, you must request SMPP credentials from support and provide your server IP address for firewall whitelisting before using the service." }, { "name": "Delivery Reports", "item": [ { "name": "SMS Delivery Reports", "item": [], "description": "Delivery reports help you track the lifecycle of each submitted SMS message, including whether it was delivered, failed, expired, rejected, or remains undeliverable.\n\n### Common Delivery Statuses\n\nDelivery report statuses show the final or latest delivery result returned for an SMS message. Use the `smsid` value from the webhook callback to match each status update with the original SMS submission in your system.\n\n| Status | Meaning | Description | Recommended Action |\n| --- | --- | --- | --- |\n| `DELIVRD` | Delivered | The message was successfully delivered to the recipient handset. | Mark the SMS as delivered in your system. |\n| `FAILED` | Failed | The message could not be delivered. This may happen because of route, operator, handset, or destination-related issues. | Mark the SMS as failed and review the destination number, route, sender ID, or message content if needed. |\n| `EXPIRED` | Expired | The message validity period expired before the SMS could be delivered. | Mark the SMS as expired. You may retry later if the message is still relevant. |\n| `UNDELIV` | Undeliverable | The message was reported as undeliverable by the SMSC, route, or mobile network. | Mark the SMS as undeliverable and check whether the mobile number is valid and reachable. |\n| `REJECTD` | Rejected | The message was rejected by the route, operator, SMSC, filtering layer, or destination rules. | Mark the SMS as rejected and review the sender ID, message content, route permissions, and destination requirements. |\n\n**Note:** Some routes may return intermediate updates before the final delivery status. Your system should update the same message record using the returned `smsid` instead of creating duplicate delivery records." }, { "name": "Delivery Report Webhook Callback", "item": [ { "name": "Webhook Endpoint Requirements", "item": [], "description": "Your webhook URL must be publicly reachable from our backend and should be able to accept `POST`, `GET`, and `HEAD` requests. Delivery report data is sent by `POST`. Our backend may also send `GET` or `HEAD` requests for connectivity checks, validation, or retry handling. You can safely ignore `GET` and `HEAD` requests, but your endpoint should still return a successful HTTP response.\n\n**Public URL**\n\nYour webhook endpoint must be accessible from the public internet. HTTPS is recommended for production integrations.\n\n**Allowed Methods**\n\nYour endpoint should accept `POST`, `GET`, and `HEAD`. Process the delivery report only when the request method is `POST`.\n\n**HTTP 200 Required**\n\nReturn `HTTP 200 OK` after receiving the callback. Any server error, timeout, blocked request, or non-200 response may be treated as a failed callback.\n\n**Fast Response**\n\nReturn the response quickly. Do not make the webhook wait for slow database actions, external APIs, or heavy processing." }, { "name": "Webhook Payload Format", "item": [], "description": "Delivery report callbacks are sent as form-style key/value data. Your endpoint should read the incoming request body and parse the delivery report fields.\n\nExample POST Bodyapplication/x-www-form-urlencoded\n\n```\nsource=YourBrand&msisdn=12345678999&status=DELIVRD&sentdate=5/14/2026+10:30:29+AM&smsid=8ff01703-5ff0-4f9e-8db7-d3263d75db07\n\n ```" }, { "name": "Webhook Parameters", "item": [], "description": "| Parameter | Example | Description |\n| --- | --- | --- |\n| `source` | `YourBrand` | The sender ID or source value used when the SMS was submitted. |\n| `msisdn` | `12345678999` | The destination mobile number that received the SMS delivery status update. |\n| `status` | `DELIVRD` | The delivery status returned for the SMS, such as delivered, failed, expired, undeliverable, or rejected. |\n| `sentdate` | `5/14/2026 10:30:29 AM` | The date and time associated with the SMS status update. The value may be URL-encoded in the webhook body. |\n| `smsid` | `8ff01703-5ff0-4f9e-8db7-d3263d75db07` | The unique SMS message ID. Use this value to match the delivery report with the original SMS submission in your system. |" }, { "name": "Delivery Status Values", "item": [], "description": "| Status | Meaning | Recommended Action |\n| --- | --- | --- |\n| `DELIVRD` | The message was delivered to the recipient handset. | Mark the message as delivered in your system. |\n| `FAILED` | The message could not be delivered. | Mark the message as failed and review the destination or route if needed. |\n| `EXPIRED` | The message validity period expired before successful delivery. | Mark the message as expired. |\n| `UNDELIV` | The message was undeliverable. | Mark the message as undeliverable and check the recipient number if needed. |\n| `REJECTD` | The message was rejected by the route, operator, or filtering layer. | Mark the message as rejected and review the sender, content, or destination rules. |" }, { "name": "Retries & Expected Response", "item": [], "description": "Your webhook endpoint should return `HTTP 200 OK` when the callback is received successfully. If your server does not respond, returns an error, blocks the request, or returns a non-200 status, our backend will retry the callback every **30 seconds** until a successful server-side response is received.\n\nExpected Response HTTP\n\n```\nHTTP/1.1 200 OK\n\n ```\n\n**Important:** Because failed callbacks are retried, your webhook should be idempotent. This means your system should safely handle the same `smsid` and `status` more than once without creating duplicate records or incorrect message states." }, { "name": "Webhook Speed & Performance", "item": [], "description": "Webhook delivery speed depends partly on your server performance, database speed, network availability, and how quickly your endpoint returns a response. If your webhook performs slow database writes, calls external services, or waits for long processing before responding, delivery report processing may become slower.\n\n| Best Practice | Why It Matters |\n| --- | --- |\n| Return `HTTP 200` quickly | A fast response confirms that your server received the callback and helps avoid unnecessary retries. |\n| Process callbacks asynchronously | Save the callback quickly or push it into a queue, then process heavier database updates in the background. |\n| Index the `smsid` field | Using an indexed message ID makes delivery report matching faster and reduces database lookup time. |\n| Avoid slow external API calls | Do not make the webhook response wait for third-party services. Process those actions after returning `HTTP 200`. |\n| Log the raw callback body | Keeping the raw callback helps with reconciliation, debugging, and support investigations. |" }, { "name": "Webhook Security", "item": [], "description": "Your webhook URL should be difficult to guess and should be protected on your side. For example, you can include a private reference value in the URL path or query string and reject requests that do not include it.\n\n**Recommended:** Use HTTPS, keep your webhook endpoint lightweight, allow `POST`, `GET`, and `HEAD`, and return `HTTP 200` only after your application has safely received the callback." } ], "description": "Delivery Report Webhook callbacks allow your system to receive automatic SMS status updates when delivery information becomes available. Instead of manually checking message status, BulkSMSOnline can send the delivery result directly to your webhook URL.\n\n**Where to set your webhook URL:** Log in to your BulkSMSOnline account, open your account settings, and add your callback URL under the **DLR Through Web Notification** section." } ], "description": "Delivery report statuses, webhook callbacks, webhook security, retries, and idempotency guidance." }, { "name": "Lookup APIs", "item": [ { "name": "MNP Lookup API", "item": [ { "name": "MNP Success Response", "item": [], "description": "On success, the API returns a JSON object containing a `results` array. The result includes the submitted MSISDN, country, operator, number type, MCC/MNC, roaming status, provider status, provider error code/description, and portability status.\n\nSuccessful Response Exampleapplication/json\n\n``` json\n {\n \"results\": [\n {\n \"msisdn\": \"12025550100\",\n \"country\": \"United States\",\n \"err_desc\": \"No Error\",\n \"operator\": \"Example Operator\",\n \"type\": \"mobile\",\n \"mccmnc\": \"310000\",\n \"is_roaming\": \"false\",\n \"err_code\": \"0\",\n \"status\": \"DELIVERED\",\n \"is_ported\": \"false\"\n }\n ]\n }\n\n ```" }, { "name": "MNP Response Fields", "item": [], "description": "| Field | Description |\n| --- | --- |\n| `results` | An array containing the MNP/HLR lookup result. |\n| `msisdn` | The submitted mobile number returned by the lookup provider. |\n| `country` | The country detected from the number issuing information. |\n| `err_desc` | The provider error description, when returned by the lookup provider. |\n| `operator` | The detected mobile network/operator name. |\n| `type` | The number type returned by the lookup provider, for example mobile or other available type. |\n| `mccmnc` | The combined Mobile Country Code and Mobile Network Code. |\n| `is_roaming` | Indicates whether the number is reported as roaming by the lookup provider. |\n| `err_code` | The provider error code returned with the lookup result. |\n| `status` | The provider status returned for the lookup request. |\n| `is_ported` | Indicates whether the number is reported as ported by the lookup provider. |" }, { "name": "MNP Error Codes", "item": [], "description": "Failed requests return a plain text response code. These codes help identify whether the issue is related to request format, authentication, balance, provider availability, or a temporary system error.\n\n| Response | Status | Description |\n| --- | --- | --- |\n| `00` | Missing Parameters | No parameters were submitted. |\n| `01` | Username Error | The username parameter is missing or empty. |\n| `02` | Password Error | The password parameter is missing or empty. |\n| `03` | MSISDN Error | The MSISDN parameter is missing or empty. |\n| `04` | Invalid MSISDN | The MSISDN format is invalid. It must be numeric, must not start with `0`, and must be between **9 and 15 digits**. |\n| `05` | Username Error | The username length is invalid. Username must be less than 30 characters. |\n| `06` | Password Error | The password length is invalid. Password must be less than 20 characters. |\n| `07` | Invalid Characters | Invalid characters were detected in one or more request parameters. |\n| `08` | Invalid Request | A parameter was sent more than once or sent in both GET and POST. |\n| `09` | Authentication Failed | Authentication failed. The username/password is incorrect, the account is not active, the account is a demo account, or the account is not allowed to use this API. |\n| `10` | Insufficient Credits | The account does not have enough available balance to complete the MNP lookup. |\n| `12` | Provider Error | The MNP/HLR provider did not return a valid response, returned an empty response, or the provider response could not be processed. |\n| `99` | System Error | Temporary system error. The request could not be processed due to an internal server, database, reporting, or routing issue. Please retry later. |\n\n**Billing note:** The MNP lookup cost is deducted only after the request format is accepted, the account is authenticated, sufficient credits are available, and the MNP/HLR provider returns a readable lookup result." }, { "name": "Endpoint", "request": { "method": "GET", "header": [], "url": { "raw": "https://api.bulksmsonline.co/mnp?username=XXXX&password=YYYYY&msisdn=12025550100", "protocol": "https", "host": [ "api", "bulksmsonline", "co" ], "path": [ "mnp" ], "query": [ { "key": "username", "value": "XXXX", "description": "Your BulkSMSOnline account username." }, { "key": "password", "value": "YYYYY", "description": "Your BulkSMSOnline account password." }, { "key": "msisdn", "value": "12025550100", "description": "Mobile number in international format without a leading + or leading 0. The value must be numeric and between 9 and 15 digits. Example: 12025550100." } ] }, "description": "The endpoint supports both **GET** and **POST**. POST is recommended because it keeps your credentials out of the URL, browser history, and most server/proxy logs.\n\nMNP Lookup Endpoint GET / POST\n\n```\nhttps://api.bulksmsonline.co/mnp?username=XXXX&password=YYYYY&msisdn=12025550100\n\n ```\n\nPOST Example Recommended\n\n```\ncurl -X POST https://api.bulksmsonline.co/mnp \\\n -d \"username=XXXX\" \\\n -d \"password=YYYYY\" \\\n -d \"msisdn=12025550100\"\n\n ```\n\n### MNP Request Parameters\n\n| Presence | Parameter | Method | Description |\n| --- | --- | --- | --- |\n| Mandatory | `username` | GET / POST | Your BulkSMSOnline account username. |\n| Mandatory | `password` | GET / POST | Your BulkSMSOnline account password. |\n| Mandatory | `msisdn` | GET / POST | Mobile number in international format without a leading `+` or leading `0`. The value must be numeric and between **9 and 15 digits**. Example: `12025550100`. |" }, "response": [] } ], "description": "Use the MNP Lookup API to check mobile number portability, roaming status, network-level details, and HLR lookup information that can help improve routing decisions, database quality, and delivery cost control." }, { "name": "MNV Number Validation API", "item": [ { "name": "MNV Success Response", "item": [], "description": "On success, the API returns a JSON object containing the detected country, network, operator, MCC/MNC, number type, network type, and the submitted MSISDN.\n\nSuccessful Response Example application/json\n\n``` json\n {\n \"Country\": \"United States\",\n \"ISO3166_2\": \"US\",\n \"CC\": \"1\",\n \"NetName\": \"Example Network\",\n \"MCC\": \"310\",\n \"MNC\": \"000\",\n \"OPERATOR\": \"Example Operator\",\n \"Type\": \"Mobile\",\n \"NetType\": \"GSM\",\n \"MSISDN\": \"12025550100\"\n }\n\n ```" }, { "name": "MNV Response Fields", "item": [], "description": "| Field | Description |\n| --- | --- |\n| `Country` | The detected country name for the submitted MSISDN. |\n| `ISO3166_2` | The two-letter ISO country code. |\n| `CC` | The country calling code. |\n| `NetName` | The detected network name. |\n| `MCC` | The Mobile Country Code. |\n| `MNC` | The Mobile Network Code. |\n| `OPERATOR` | The detected mobile operator name. |\n| `Type` | The number type returned by the validation database. |\n| `NetType` | The detected network type, when available. |\n| `MSISDN` | The submitted mobile number. |" }, { "name": "MNV Error Codes", "item": [], "description": "Failed requests return a plain text response code. These codes help you identify whether the issue is related to request format, authentication, balance, number validation, or a temporary system error.\n\n| Response | Status | Description |\n| --- | --- | --- |\n| `00` | Missing Parameters | No parameters were submitted. |\n| `01` | Username Error | The username parameter is missing or empty. |\n| `02` | Password Error | The password parameter is missing or empty. |\n| `03` | MSISDN Error | The MSISDN parameter is missing or empty. |\n| `04` | Invalid MSISDN | The MSISDN format is invalid. It must be numeric, must not start with `0`, and must be between **9 and 15 digits**. |\n| `05` | Username Error | The username length is invalid. Username must be less than 30 characters. |\n| `06` | Password Error | The password length is invalid. Password must be less than 20 characters. |\n| `07` | Invalid Characters | Invalid characters were detected in one or more request parameters. |\n| `08` | Invalid Request | A parameter was sent more than once or sent in both GET and POST. |\n| `09` | Authentication Failed | Authentication failed. The username/password is incorrect, the account is not active, the account is a demo account, or the account is not allowed to use this API. |\n| `10` | Insufficient Credits | The account does not have enough available balance to complete the MNV lookup. |\n| `11` | No MNV Data | The number format is valid, but no MNV data was found for the submitted MSISDN. |\n| `99` | System Error | Temporary system error. The request could not be processed due to an internal server, database, or routing issue. Please retry later. |\n\n**Billing note:** The MNV lookup cost is deducted only after the number format is accepted, the account is authenticated, sufficient credits are available, and MNV data is successfully found." }, { "name": "Endpoint", "request": { "method": "GET", "header": [], "url": { "raw": "https://api.bulksmsonline.co/mnv?username=XXXX&password=YYYYY&msisdn=12025550100", "protocol": "https", "host": [ "api", "bulksmsonline", "co" ], "path": [ "mnv" ], "query": [ { "key": "username", "value": "XXXX", "description": "Your BulkSMSOnline account username." }, { "key": "password", "value": "YYYYY", "description": "Your BulkSMSOnline account password." }, { "key": "msisdn", "value": "12025550100", "description": "Mobile number in international format without a leading + or leading 0. The value must be numeric and between 9 and 15 digits. Example: 12025550100." } ] }, "description": "The endpoint supports both **GET** and **POST**. POST is recommended because it keeps your credentials out of the URL, browser history, and most server/proxy logs.\n\nMNV EndpointGET / POST\n\n```\nhttps://api.bulksmsonline.co/mnv?username=XXXX&password=YYYYY&msisdn=12025550100\n\n ```\n\nPOST ExampleRecommended\n\n```\ncurl -X POST https://api.bulksmsonline.co/mnv \\\n -d \"username=XXXX\" \\\n -d \"password=YYYYY\" \\\n -d \"msisdn=12025550100\"\n\n ```\n\n### MNV Request Parameters\n\n| Presence | Parameter | Method | Description |\n| --- | --- | --- | --- |\n| Mandatory | `username` | GET / POST | Your BulkSMSOnline account username. |\n| Mandatory | `password` | GET / POST | Your BulkSMSOnline account password. |\n| Mandatory | `msisdn` | GET / POST | Mobile number in international format without a leading `+` or leading `0`. The value must be numeric and between **9 and 15 digits**. Example: `12025550100`. |" }, "response": [] } ], "description": "Use the MNV API to validate mobile numbers, improve contact database quality, identify invalid entries, and reduce wasted SMS attempts caused by incorrectly formatted or unsupported numbers." } ], "description": "MNP lookup and MNV number validation API documentation, response fields, billing notes, and error codes." } ], "event": [ { "listen": "prerequest", "script": { "type": "text/javascript", "packages": {}, "requests": {}, "exec": [ "" ] } }, { "listen": "test", "script": { "type": "text/javascript", "packages": {}, "requests": {}, "exec": [ "" ] } } ] }