GET - Retrieve batch messages

Retrieves messages and their delivery statuses for a given batch ID. Use this endpoint to check the delivery outcome of messages sent via Batch Send.

GET /campaigns/:campaignId/batch/:batchId/messages

---

Path Parameters

Parameter	Type	Required	Description
campaignId	string	Yes	The ID of the campaign the batch belongs to.
batchId	string	Yes	The ID of the batch to retrieve. This is the batchId returned from the Batch Send response.

---

Query Parameters

This endpoint supports cursor-based pagination and search.

Parameter	Type	Required	Description
limit	number	No	Number of results per page.
search	string	No	Filter by recipient phone number. This is a substring match (e.g. "11" would match "91122233").
after	string	No	Cursor for fetching the next page. Use the endCursor value from the previous response's pageData.
before	string	No	Cursor for fetching the previous page. Use the startCursor value from the previous response's pageData.

---

Request Headers

Header	Value	Required
Authorization	Bearer YOUR_API_KEY	Yes

---

Request Body

This endpoint does not require a request body.

---

Response

HTTP 200 OK

Returns a paginated list of message objects with delivery statuses.

{
  "data": [
    {
      "createdAt": "2024-05-16T16:34:06.582+08:00",
      "updatedAt": "2024-05-16T16:36:05.595+08:00",
      "id": "<YOUR_MESSAGE_ID>",
      "recipient": "6599999999",
      "values": {
        "body": "test"
      },
      "fullMessage": "<YOUR_FULL_MESSAGE>",
      "latestStatus": "success",
      "templateBodyId": "<YOUR_TEMPLATE_BODY_ID>",
      "campaignId": "<YOUR_CAMPAIGN_ID>",
      "templateBody": {
        "createdAt": "2024-05-06T11:00:03.467+08:00",
        "updatedAt": "2024-05-06T11:00:03.467+08:00",
        "id": "<YOUR_TEMPLATE_BODY_ID>",
        "templateId": "<YOUR_TEMPLATE_ID>",
        "language": "english",
        "body": "{{body}}",
        "creatorId": "<YOUR_CREATOR_ID>"
      },
      "messageAttempts": [
        {
          "sentAt": "2024-05-16T16:35:43.009+08:00",
          "deliveredAt": null,
          "createdAt": "2024-05-16T16:34:06.604+08:00",
          "updatedAt": "2024-05-16T16:36:05.593+08:00",
          "id": "<YOUR_MESSAGE_ATTEMPT_ID>",
          "messageId": "<YOUR_MESSAGE_ID>",
          "externalAttemptId": "<YOUR_EXTERNAL_ATTEMPT_ID>",
          "status": "success",
          "errorType": null,
          "errorCode": null,
          "metadata": {},
          "creatorId": "<YOUR_CREATOR_ID>",
          "creator": {
            "email": "<YOUR_CREATOR_EMAIL>"
          }
        }
      ],
      "language": "english",
      "creatorEmail": "<YOUR_CREATOR_EMAIL>",
      "creatorId": "<USER_ID_OF_MESSAGE_CREATOR>",
      "numAttempts": 1
    },
    {
      "createdAt": "2024-05-16T16:34:06.582+08:00",
      "updatedAt": "2024-05-16T16:35:13.122+08:00",
      "id": "<YOUR_MESSAGE_ID>",
      "recipient": "6522222222",
      "values": {
        "body": "test"
      },
      "fullMessage": "<YOUR_FULL_MESSAGE>",
      "latestStatus": "failure",
      "templateBodyId": "<YOUR_TEMPLATE_BODY_ID>",
      "campaignId": "<YOUR_CAMPAIGN_ID>",
      "templateBody": {
        "createdAt": "2024-05-06T11:00:03.467+08:00",
        "updatedAt": "2024-05-06T11:00:03.467+08:00",
        "id": "<YOUR_TEMPLATE_BODY_ID>",
        "templateId": "<YOUR_TEMPLATE_ID>",
        "language": "english",
        "body": "{{body}}",
        "creatorId": "<YOUR_CREATOR_ID>"
      },
      "messageAttempts": [
        {
          "sentAt": "2024-05-16T16:35:13.118+08:00",
          "deliveredAt": null,
          "createdAt": "2024-05-16T16:34:06.604+08:00",
          "updatedAt": "2024-05-16T16:35:13.118+08:00",
          "id": "<YOUR_MESSAGE_ATTEMPT_ID>",
          "messageId": "<YOUR_MESSAGE_ID>",
          "externalAttemptId": "",
          "status": "failure",
          "errorType": "server_error",
          "errorCode": "server_unknown_error",
          "metadata": {},
          "creatorId": "<YOUR_CREATOR_ID>",
          "creator": {
            "email": "<YOUR_CREATOR_EMAIL>"
          }
        }
      ],
      "language": "english",
      "creatorEmail": "<YOUR_CREATOR_EMAIL>",
      "creatorId": "<USER_ID_OF_MESSAGE_CREATOR>",
      "numAttempts": 1
    }
  ],
  "pageData": {
    "hasNextPage": false,
    "hasPreviousPage": false,
    "startCursor": "WyIyMDI0LTA1LTE2VDE2OjM0OjA2LjU5MCswODowMCIsIjMwMjE5Il0=",
    "endCursor": "WyIyMDI0LTA1LTE2VDE2OjM0OjA2LjU5MCswODowMCIsIjMwMjE3Il0="
  }
}

Top-level response fields

Field	Type	Description
data	array	Array of message objects.
pageData	object	Pagination metadata (see below).

Message object fields

Field	Type	Description
createdAt	string	ISO 8601 timestamp of when the message was created.
updatedAt	string	ISO 8601 timestamp of the last update to the message.
id	string	The unique message ID.
recipient	string	The recipient's phone number.
values	object	The template parameter values used in the message.
fullMessage	string	The full rendered message text, including Postman's header and footer.
latestStatus	string	The current delivery status. See Message Statuses for all possible values.
templateBodyId	string	The ID of the template body used.
campaignId	string	The campaign ID the message belongs to.
templateBody	object	The template body object containing id, templateId, language, body, and creatorId.
messageAttempts	array	Array of delivery attempt objects (see below).
language	string	The language used for the message.
creatorEmail	string	The email address of the message creator.
creatorId	string	The user ID of the message creator.
numAttempts	number	Total number of delivery attempts for this message.

messageAttempts array

Each attempt object contains the delivery attempt details.

Field	Type	Description
sentAt	string	ISO 8601 timestamp of when the message was sent to the provider.
deliveredAt	string or null	ISO 8601 timestamp of when the message was delivered. null if not delivered.
createdAt	string	ISO 8601 timestamp of when the attempt was created.
updatedAt	string	ISO 8601 timestamp of the last update to the attempt.
id	string	The unique attempt ID.
messageId	string	The message ID this attempt belongs to.
externalAttemptId	string	The external attempt ID from the messaging service provider. May be empty.
status	string	The status of this attempt (e.g. success, failure, sent).
errorType	string or null	The error type if the attempt failed: delivery_error or server_error. null if no error.
errorCode	string or null	The error code if the attempt failed. See Message Delivery Errors for the full list. null if no error.
metadata	object	Additional metadata for the attempt.
creatorId	string	The user ID of the message creator.
creator	object	Object containing the email of the message creator.

pageData object

Field	Type	Description
hasNextPage	boolean	Whether there is a next page of results.
hasPreviousPage	boolean	Whether there is a previous page of results.
startCursor	string	Cursor for the first record on the current page. Use with the before query parameter.
endCursor	string	Cursor for the last record on the current page. Use with the after query parameter.

---

Error Responses

HTTP 401 Unauthorized

Error Code	Message	Cause
invalid_api_key_provided	The API key provided is invalid.	API key is incorrect, expired, or deleted.
invalid_ip_address_error	The IP address used for this request is invalid.	Request sent from a non-whitelisted IP address.

HTTP 404 Not Found

The batch ID does not exist or belongs to a campaign you do not have access to.

HTTP 429 Too Many Requests

Error Code	Message	Cause
too_many_requests	Too many requests	Rate limit exceeded. Default is 10 TPS per campaign, shared across all endpoints. Implement exponential backoff and retry.

---

Example: cURL

curl -X GET \
  "https://postman.gov.sg/api/v2/campaigns/<YOUR_CAMPAIGN_ID>/batch/<YOUR_BATCH_ID>/messages" \
  -H "Authorization: Bearer YOUR_API_KEY"

With pagination and search:

curl -X GET \
  "https://postman.gov.sg/api/v2/campaigns/<YOUR_CAMPAIGN_ID>/batch/<YOUR_BATCH_ID>/messages?limit=10&search=9999&after=<END_CURSOR>" \
  -H "Authorization: Bearer YOUR_API_KEY"

---

Notes

• Results are sorted by createdAt followed by id.

• The search parameter performs a substring match on the recipient phone number. For example, searching for "11" will match "91122233".

• Webhooks for delivery status updates are not currently supported. You must poll this endpoint to check for status changes.

• Telcos do not provide read statuses. The terminal statuses are success (delivered) and failure (failed).

• To retry failed messages in the batch, use the Retry Batch Send endpoint.