Go to Postman v1

List Emails API

This API allows you to retrieve previously sent emails.

GET /v1/transactional/email

The above returns the first 10 emails sorted by created_at in descending order

Request body for listing transactional emails

eg. Response Body
const response = await fetch('/v1/transactional/email', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Query Parameters

limit integer

max number of messages returned

offset integer

offset to begin returning messages from

`offset` endpoint example
GET /transactional/email?limit=20&offset=10

The example above returns the next 20 emails sorted by created_at in descending order

status array of enums

status of messages to filter for.

This return emails with the specified status. For a list of possible values, see this section

item enum

  • UNSENT

  • ACCEPTED

  • SENT

  • BOUNCED

  • DELIVERED

  • OPENED

  • COMPLAINT

`delivered` status example
GET /transactional/email?status=DELIVERED

The example above returns the first 10 emails with the status delivered, soered by created_at in descending order.

created_at object

Filter for created_at timestamp of messages that corresponds to the time the API call to send the email was made.

For created_at, the timestamp should be specified in valid ISO 8601 format. The list of supported operators are:

`get` status time example
GET /transactional/email?created_at[gt]=2023-05-10T03:03:54.163Z

The example above returns the first 10 emails created after 2023-05-10T03:03:54.163Z ,sorted by created_at in descending order. Do note that if the timezone is not specified, it will be assumed to be UTC.

`get` status example
GET /transactional/email?created_at[gt]=2023-05-03&created_at[lt]=2023-05-10

Returns the first 10 emails created between 2023-05-03 and 2023-05-10 sorted by created_at in descending order.

sort_by array of enum

The default sorting option is created_at, descending.

We currently support the following sorting options:

  • created_at: sort by the time when the email was created; this roughly corresponds to the time when the API call to send the email was made

  • updated_at: sort by the time when the email was last updated

We support both ascending and descending order.

To specify the order, add the prefix + for ascending order and - for descending order.

For example, +created_at will sort by created_at in ascending order, and -updated_at will sort by updated_at in descending order. If the prefix is omitted, descending order will be used.

`sorted_by` example
GET /transactional/email?sort_by=+created_at&created_at[gte]=2022-11-01&status=delivered&limit=48

Returns the first 48 emails with status DELIVERED created on or after 2022-11-01 sorted by created_at in ascending order.

Response body for listing emails API

Listing emails API response example
{
  "has_more": false,
  "data": [
    {
      "id": 42,
      "from": "Postman <info@mail.postman.gov.sg>",
      "recipient": "hello@example.com",
      "params": {
        "body": "Hello World",
        "from": "Postman <info@mail.postman.gov.sg>",
        "subject": "Hello World",
        "reply_to": "hello@example.com"
      },
      "attachments_metadata": [
        {
          "fileName": "text",
          "fileSize": 0,
          "hash": "text"
        }
      ],
      "status": "UNSENT",
      "error_code": "text",
      "error_sub_type": "text",
      "created_at": "2024-09-02T01:34:37.342Z",
      "updated_at": "2024-09-02T01:34:37.342Z",
      "accepted_at": "2024-09-02T01:34:37.342Z",
      "sent_at": "2024-09-02T01:34:37.342Z",
      "delivered_at": "2024-09-02T01:34:37.342Z",
      "opened_at": "2024-09-02T01:34:37.342Z"
    }
  ]

The response is a JSON object with the following fields:

  • has_more: a boolean indicating whether there are more emails to retrieve

  • data: an array of JSON email objects. You can find an example of a single JSON email object here. We support excluding the params field from the response object, see this section for more information.

Excluding params Field from Response

Depending on the email body, the params field could be fairly large and unnecessary to users who are calling this API to retrieve the latest status.

As such, we support an optional exclude_params field that allows you to exclude the params field from the response. To do so, set exclude_params to true in the query parameters, i.e. GET /transactional/email?exclude_params=true. If exclude_params is not specified, the params field will be included in the response.

PreviousGet Email by ID APINextProgrammatic GovSG WhatsApp API

Last updated