Your First API Request
Send your very first transactional SMS message in under five minutes with copy-pasteable examples in cURL, TypeScript, Python, PHP, and Java.
This guide sends the first SMS with an sk_test_ key on https://api.smspro.com. Magic numbers keep the send simulated and free of wallet charges.
1. The API Request
To send a message, submit an HTTP POST request to the /api/v1/public/sms/send endpoint.
Select your language of choice below to copy a complete, functional code sample:
curl -X POST "https://api.smspro.com/api/v1/public/sms/send" \
-H "X-Api-Key: sk_test_948f293048a1b2c3d4e5f60718" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)" \
-d '{
"to": "+233200000001",
"senderId": "SMSPRO",
"message": "Welcome to SMS Pro! Your first API test is successful."
}'2. Request Component Breakdown
Let's dissect each component of the request:
HTTP Headers
X-Api-Key: Authenticates the call.sk_test_simulates delivery on this same API.Content-Type: application/json: Signals to the gateway that the request body is a JSON-encoded string.Idempotency-Key: A random UUID identifying this specific transmission attempt. If network connectivity drops and your client retries the exact same call, the gateway guarantees the message will not be queued a second time.
JSON Request Body
to: Destination phone number. In this example,+233200000001is a reserved Sandbox Magic Number that causes the mock gateway to simulate an immediate successful delivery (DELIVERED). In production, SMS Pro accepts local format (0241234567), international without plus (233241234567), and standard E.164 (+233241234567), normalizing them automatically.senderId: Up to 11 alphanumeric characters (e.g.SMSPRO).message: The text string to deliver to the recipient.
3. Dissecting the Response
A successful dispatch returns HTTP 202 Accepted. The 202 status code indicates that the message has been validated, accepted by the ingestion pipeline, and queued for telco transmission:
{
"status": "success",
"message": "Queued",
"data": {
"jobId": "job-d41d8cd9-8f00-4b11-b841-892104ab0123",
"messageIds": ["c7a8b9e0-1234-5678-9abc-def012345678"],
"messageId": "c7a8b9e0-1234-5678-9abc-def012345678",
"status": "ACCEPTED",
"segmentCount": 1,
"totalUnits": 1
}
}Response Fields Explained
jobId: Identifier for the background dispatch job. For bulk sends, one job encompasses many messages.messageId: Unique identifier for this specific recipient delivery. Store this key in your database to correlate future delivery receipts (DLR).status: Current pipeline state. Begins atACCEPTEDorQUEUED, and later transitions toSENT,DELIVERED, orFAILED.segmentCount: The number of 160-character (GSM-7) or 70-character (UCS-2) SMS segments computed for your message text.totalUnits: Billing unit cost calculated for this dispatch (in sandbox, 0 balance is deducted).
4. Polling Delivery Status
To query the current state of your message, send a GET request to /api/v1/public/sms/messages/{messageId}:
curl -X GET "https://api.smspro.com/api/v1/public/sms/messages/c7a8b9e0-1234-5678-9abc-def012345678" \
-H "X-Api-Key: sk_test_948f293048a1b2c3d4e5f60718"Because +233200000001 is a success magic number, the status will immediately report DELIVERED:
{
"status": "success",
"message": "Message details retrieved",
"data": {
"id": "c7a8b9e0-1234-5678-9abc-def012345678",
"to": "+233200000001",
"senderId": "SMSPRO",
"status": "DELIVERED",
"deliveredAt": "2026-11-18T08:45:10Z"
}
}Next Step
Learn how to parse standard response envelopes, handle HTTP status codes, and manage errors in Understanding Responses.