Complete SMS API Documentation & Integration Guide

Complete guide to integrate Send99 SMS Gateway API with your application. Learn how to send SMS, check balance, and get delivery reports. For a product overview, see the HTTP SMS API page.

1. Get Balance

Method: HTTP GET

Endpoint: http://smscp.send99.com:20003/getbalance?account=***&password=***

Necessary Parameters:

account (String) - Your account username

password (String) - API password, can be found on Dashboard

Optional Parameters:

version (String, default: "1.0") - Protocol version number

seq (Int, default: 1) - Serial number, increments per request

time (Int) - Timestamp from which the request was made

Response:


{
    "status": 0,
    "balance": "99.990000",
    "gift": "50.00000"
}

2. Send SMS

Method: HTTP GET or POST

Endpoint (GET): http://smscp.send99.com:20003/sendsms?account=***&password=***&smstype=0&numbers=10010,1008611&content=***&mmstitle=mmstitle_text

Endpoint (POST): http://smscp.send99.com:20003/sendsms

Necessary Parameters:

account (String) - Your account username

password (String) - API password, can be found on Dashboard

numbers (String) - SMS receiving number, separated by English comma between multiple numbers

content (String) - Send content

Optional Parameters:

version (String, default: "1.0") - Protocol version number

seq (Int, default: 1) - Serial number, increments per request

time (Int) - Timestamp from which the request was made

smstype (Int, default: 0) - SMS type (0: SMS, 1: MMS)

mmstitle (String) - MMS title (URL-encoded for GET mode)

sender (String) - Sender

sendtime (String) - Timed delivery time

Response:


{
    "status": 0,
    "success": 2,
    "fail": 0,
    "array": [
        [10010, 1],
        [1008611, 2]
    ]
}

3. Get Report

Method: HTTP GET

Endpoint: http://smscp.send99.com:20003/getreport?account=***&password=***&ids=1,2

Necessary Parameters:

account (String) - Your account username

password (String) - API password, can be found on Dashboard

ids (String) - Specify the SMS id of the query sending result

Optional Parameters:

version (String, default: "1.0") - Protocol version number

seq (Int, default: 1) - Serial number, increments per request

time (Int) - Timestamp from which the request was made

Response:


{
    "status": 0,
    "success": 1,
    "fail": 1,
    "unsent": 0,
    "sending": 0,
    "nofound": 0,
    "array": [
        [1, 10010, 20171001123015, 0],
        [2, 1008611, 20171001123015, 3]
    ]
}

4. Get SMS

Method: HTTP GET

Endpoint: http://smscp.send99.com:20003/getsms?account=***&password=***

Necessary Parameters:

account (String) - Your account username

password (String) - API password, can be found on Dashboard

Optional Parameters:

version (String, default: "1.0") - Protocol version number

seq (Int, default: 1) - Serial number, increments per request

time (Int) - Timestamp from which the request was made

ids (String) - Specify the SMS id of the query sending result

Response:


{
    "status": 0,
    "cnt": 2,
    "array": [
        [1, 10010, 20171001123015, "content"],
        [2, 1008611, 20171001123015, "content"]
    ]
}

Authentication and request basics

Every documented request uses your account username and API password, which you can find in the dashboard. Optional parameters include a protocol version, a sequence number, and a timestamp. Keep the credentials server-side, use one account per environment where possible, and contact support for the HTTPS endpoint and IP allowlisting before production.

The examples on this page use placeholder credentials (***). Never place real credentials in documentation, client-side code, public repositories, or support tickets. If a credential may have been exposed, rotate it and review recent sends for unexpected traffic.

Response codes and error handling

Responses are JSON. A top-level status of 0 indicates that the request was processed; per-message arrays then show which recipients succeeded and which failed. Report responses also distinguish messages that are unsent, still sending, or not found. Build your integration around these values rather than assuming every accepted request means every message was delivered.

Classify failures before retrying. Invalid numbers and blocked content are usually permanent, while network or queue congestion may be transient. Apply a bounded retry policy with backoff, log the response, and suppress numbers that fail repeatedly. Ask support for the current error-code list if you need to map statuses to your own alerting.

Delivery reports and inbound messages

The report endpoint returns delivery state for the message IDs you specify. The inbound endpoint returns messages that recipients sent back to your number, which is the foundation for two-way SMS. Poll at a sensible interval for low-volume flows, or ask about webhook delivery for production systems that need near-real-time updates.

Persist message IDs and timestamps so you can reconcile reports with your own orders, appointments, or alerts. For support investigations, include the message ID, destination country, sender ID, and approximate send time — never the account password.

Production integration checklist

Before launch: confirm the sender type and registration for each destination, test with real handsets on the target networks, verify delivery-report handling, and define what happens when the API times out. Add monitoring for error rates and queue depth, and keep an owner for credential rotation and incident response.

For higher throughput, compare the HTTP API with SMPP. SMPP can be a better fit for large, sustained volumes and direct bind management, while HTTP is simpler for event-driven application messaging. The HTTP SMS API overview explains the trade-offs.

Frequently asked questions

How do I authenticate with the Send99 SMS API?

Use the account username and API password from your dashboard as request parameters. Keep them server-side, use separate credentials by environment where possible, and ask support for the HTTPS endpoint and IP allowlisting before production. Never put real credentials in client-side code or public repositories.

What does a successful send response contain?

A successful response includes a status value, counts of successful and failed submissions, and an array of per-recipient message IDs. Store those IDs: they are required for delivery-report queries and for reconciling sends with your own orders, alerts, or appointments.

How do I retrieve delivery reports?

Call the report endpoint with the message IDs returned by the send call. The response distinguishes success, failure, unsent, sending, and not-found messages. Use those values to drive retries, alerting, and suppression of persistently invalid numbers rather than retrying every non-success blindly.

Does the API support inbound messages?

Yes. The inbound-message endpoint returns replies sent to your number, which supports two-way SMS and keyword flows. Poll at an interval that matches your response-time needs, or ask about webhook delivery for production systems that need near-real-time updates.

Can I test the API before going live?

Yes. Test credits let you validate credentials, send to your own handsets, and inspect real delivery reports. Start with a small set of numbers on the target networks, confirm the response handling, then fund a production balance and complete any required sender registration.

What should I do if an API call times out?

Treat a timeout as an unknown outcome, not automatic failure. Record the request, check whether the message ID was created, and retry with a bounded policy to avoid duplicates. Use a queue and idempotency in your own layer, and monitor error rates so a downstream problem is visible before it affects a campaign.