Messages

View sent message history and track delivery status through the message lifecycle.

Message Statuses

Every message in Postject moves through a series of statuses as it progresses from creation to delivery. The following table describes each possible status:

Status	Description
`queued`	The message has been accepted by the API and is waiting to be processed.
`sending`	The message is being transmitted to the mail provider for delivery.
`sent`	The message has been successfully handed off to the recipient's mail server.
`delivered`	The recipient's mail server confirmed receipt of the message.
`bounced`	The message was rejected by the recipient's mail server. This can be a hard bounce (invalid address) or a soft bounce (temporary issue).
`complained`	The recipient marked the email as spam. The address is automatically added to the suppression list.
`rejected`	The message was rejected before sending, typically because the recipient is on the suppression list or the sender identity is not verified.
`failed`	The message could not be sent due to an internal error or configuration issue. Check the event metadata for details.

List Messages

Returns a paginated list of messages for a given stream. Messages are ordered by creation date, with the most recent messages first.

GEThttps://api.postject.com/v1/messages

Query Parameters

streamIdstring (required)

The ID of the message stream to retrieve messages from.

pagenumber (optional)

The page number to retrieve. Defaults to 1.

limitnumber (optional)

The number of messages per page. Defaults to 20, maximum 100.

json

{
  "data": [
    {
      "id": "msg_01hy4z8k2a3b4c5d",
      "to": "alice@example.com",
      "from": "noreply@yourdomain.com",
      "subject": "Your order has been shipped",
      "status": "delivered",
      "createdAt": "2025-07-15T14:32:00.000Z",
      "sentAt": "2025-07-15T14:32:01.456Z"
    },
    {
      "id": "msg_02iz5a9l3b4c5d6e",
      "to": "bob@example.com",
      "from": "noreply@yourdomain.com",
      "subject": "Password reset request",
      "status": "delivered",
      "createdAt": "2025-07-15T14:28:00.000Z",
      "sentAt": "2025-07-15T14:28:00.892Z"
    }
  ],
  "meta": {
    "total": 1284,
    "page": 1,
    "limit": 20,
    "pages": 65
  }
}

Get Message Details

Retrieves the full details of a single message, including the complete event history ordered by timestamp. Use this to inspect the delivery lifecycle of any message.

GEThttps://api.postject.com/v1/messages/:id

json

{
  "id": "msg_01hy4z8k2a3b4c5d",
  "streamId": "clx8f2k9a0002uy7z1a2b3c4d",
  "to": "alice@example.com",
  "from": "noreply@yourdomain.com",
  "subject": "Your order has been shipped",
  "html": "<p>Hi Alice, your order #4821 has been shipped and is on its way.</p>",
  "status": "delivered",
  "sesMessageId": "010201900a1b2c3d-4e5f6a7b-8c9d-0e1f-2a3b-4c5d6e7f8a9b-000000",
  "templateId": "clx9c5o3d0007xz0z2p3q4r5s",
  "createdAt": "2025-07-15T14:32:00.000Z",
  "sentAt": "2025-07-15T14:32:01.456Z",
  "events": [
    {
      "id": "evt_a1b2c3d4e5f6",
      "type": "sent",
      "timestamp": "2025-07-15T14:32:01.456Z",
      "metadata": {
        "sesMessageId": "010201900a1b2c3d-4e5f6a7b-8c9d-0e1f-2a3b-4c5d6e7f8a9b-000000"
      }
    },
    {
      "id": "evt_g7h8i9j0k1l2",
      "type": "delivered",
      "timestamp": "2025-07-15T14:32:03.789Z",
      "metadata": {
        "smtpResponse": "250 2.0.0 OK",
        "processingTimeMs": 2333
      }
    },
    {
      "id": "evt_m3n4o5p6q7r8",
      "type": "opened",
      "timestamp": "2025-07-15T15:10:22.000Z",
      "metadata": {
        "userAgent": "Mozilla/5.0",
        "ipAddress": "203.0.113.42"
      }
    }
  ]
}