API Reference

Base URLs

All API requests should be made to the following base URLs:

Production

To send SMSes to the public, please use our production environment.

https://postman.gov.sg/api/v2

Do not use this for testing, please use our test or loadtest environments instead. Non-compliance will be reported to your agency's CIO.

Test

Loadtest

---

Authentication

The Postman v2 API uses API keys and static IP whitelisting to authenticate requests. Authentication is performed with HTTP Bearer Auth.

Authorization: Bearer YOUR_API_KEY

All API calls must be made over HTTPS. Calls over plain HTTP will fail. Requests without authentication will return HTTP 401.

---

API Endpoints

Single send (for a single recipient)

HTTP Method	Endpoint	Description
POST	/campaigns/:campaignId/messages	Send a single message to one recipient. Use this for time-sensitive, critical SMSes like OTPs or weather alerts. Returns the created message object immediately, but you must query the Retrieve Message endpoint to get the delivery status.
POST	/campaigns/:campaignId/messages/:messageId/retry	Retry a single failed message. The message retains its original message ID. Only works if the message latestStatus is failure. Maximum 3 retry attempts per message.
GET	/campaigns/:campaignId/messages/:messageId	Retrieve a single message and its delivery status. Webhooks are not supported; you must poll this endpoint to check status changes.
GET	/campaigns/:campaignId/messages	Retrieve all messages and their delivery statuses for a campaign, with campaign template information. Supports searching by recipient phone number (substring match). Returns paginated results.

Batch send (for multiple recipients)

HTTP Method	Endpoint	Description
POST	/campaigns/:campaignId/batch/messages	Send messages to multiple recipients in a single API request. Upload a CSV file via multipart/form-data. The CSV must include recipient, language, and columns for each template parameter. Test environment has a 20-row CSV limit.
POST	/campaigns/:campaignId/batch/:batchId/retry	Retry all failed messages in a batch. Only works if batch status is messages_enqueued or messages_enqueuing_failed. Will fail if any message in the batch still has latestStatus of created. Returns HTTP 201 with no response body.
GET	/campaigns/:campaignId/batch/:batchId/messages	Retrieve all messages and their delivery statuses for a batch. Supports searching by recipient phone number (substring match). Returns paginated results using cursor-based pagination.

---

Pagination

The Retrieve Batch and Retrieve Campaign Message endpoints use cursor-based pagination.

Parameter	Description
limit	Number of results per page
search	Filter by recipient phone number (substring match)
before	Cursor for fetching the previous page
after	Cursor for fetching the next page

The response includes a pageData object:

{
  "pageData": {
    "hasNextPage": false,
    "hasPreviousPage": false,
    "startCursor": "...",
    "endCursor": "..."
  }
}

Use after with endCursor to get the next page. Use before with startCursor to get the previous page.

---

Message Statuses

Status	Description
created	Postman has created the message record but has not yet sent it to the messaging service provider.
enqueued	The message is in the queue, waiting to be sent to the messaging service provider.
sending	The message has been taken out of the queue and is being sent to the messaging service provider.
sent	Postman has sent the message to the messaging service provider, but has not yet received a delivery confirmation.
sent_to_telco	The messaging service provider confirms the message has been sent to the recipient's telco. The message may or may not have reached the recipient's phone. If status remains here beyond 48 hours, a further update is unlikely.
success	The message has been delivered to the recipient. This is a terminal status.
failure	The message failed to send due to an error in Postman or the messaging service. This is a terminal status. See Message Delivery Errors for details.

---

Rate Limits

The default rate limit is 10 TPS (transactions per second) per campaign ID. This is defined as the number of API calls per second, not the number of messages sent per second. The rate limit is shared across all API endpoints for a campaign.

Requests that exceed the rate limit are dropped (not queued) and return HTTP 429. You must retry these requests yourself.

To request a higher TPS, we require evidence of historical usage from your old systems where rate limits have been hit.

---