search
Go to Postman v2

GET - Retrieve a single message

Retrieves a single message and its delivery status.

Postman does not support pushing delivery status to your server via webhooks when the status of a message changes. You must poll this endpoint to get the message latestStatus.

GET /campaigns/:campaignId/messages/:messageId

Path Parameters

Parameter
Type
Required
Description

campaignId

string

Yes

The ID of the campaign the message belongs to.

messageId

string

Yes

The ID of the message to retrieve. This is the id returned from the Single Send or Single Send - Retry response.

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 the message object with full delivery status, template information, and attempt history.

{
  "createdAt": "2024-05-16T10:30:50.904+08:00",
  "updatedAt": "2024-05-16T10:30:50.965+08:00",
  "id": "<YOUR_MESSAGE_ID>",
  "recipient": "6599999999",
  "values": {
    "name": "John Doe",
    "fruit": "apple"
  },
  "fullMessage": "<YOUR_FULL_MESSAGE>",
  "latestStatus": "success",
  "templateBodyId": "<YOUR_TEMPLATE_BODY_ID>",
  "campaignId": "<YOUR_CAMPAIGN_ID>",
  "templateBody": {
    "createdAt": "2024-05-16T10:13:15.111+08:00",
    "updatedAt": "2024-05-16T10:13:15.111+08:00",
    "id": "<YOUR_TEMPLATE_BODY_ID>",
    "templateId": "<YOUR_TEMPLATE_ID>",
    "language": "english",
    "body": "Dear {{name}}, here is your {{fruit}}.",
    "creatorId": "<YOUR_CREATOR_ID>"
  },
  "batches": [],
  "language": "english",
  "creatorEmail": "<YOUR_CREATOR_EMAIL>",
  "creatorId": "<USER_ID_OF_MESSAGE_CREATOR>",
  "attempts": [
    {
      "status": "success",
      "createdAt": "2024-05-16T10:57:52.534+08:00"
    }
  ]
}

Response 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 (see below).

batches

array

Array of batch objects if the message was sent as part of a batch. Empty array for single send messages.

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.

attempts

array

Array of delivery attempt objects (see below).

templateBody object

Field
Type
Description

createdAt

string

ISO 8601 timestamp of when the template body was created.

updatedAt

string

ISO 8601 timestamp of the last update to the template body.

id

string

The template body ID.

templateId

string

The parent template ID.

language

string

The language of this template body.

body

string

The raw template body with {{variables}} placeholders.

creatorId

string

The user ID of the template creator.

attempts array

Each attempt object contains the status and timestamp for a delivery attempt. If the status is failure, there will be an additional error object.

Field
Type
Description

status

string

The status of this attempt: success or failure.

createdAt

string

ISO 8601 timestamp of when the attempt was created.

sentAt

string

ISO 8601 timestamp of when the message was sent to the provider. Present on failure attempts.

deliveredAt

string or null

ISO 8601 timestamp of when the message was delivered. null if not delivered.

error

object

Present only on failure attempts. Contains type and code fields.

error object (within an attempt)

Field
Type
Description

type

string

The error type: delivery_error or server_error.

code

string

The error code. See Message Delivery Errors for the full list.

Example response with a failed attempt followed by a successful retry:

In this example, the first attempt failed with server_unknown_error. After a retry via the Single Send - Retryarrow-up-right endpoint, the second attempt succeeded. The latestStatus reflects the most recent outcome.

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 message 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

Notes

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

  • The attempts array shows the full history of delivery attempts, including any retries. The most recent attempt is listed first.

  • The latestStatus field reflects the outcome of the most recent attempt.

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

  • SMSes with failure as the latestStatus will not be charged.

  • If latestStatus is sent_to_telco beyond 48 hours, it is unlikely that a further status update will be received. This is a telco limitation.

PreviousPOST - Retry single sendNextPOST - Batch send

Last updated

Was this helpful?