List Emails API

This API allows you to retrieve previously sent emails.

List transactional emails

GET/v1/transactional/email

Authorization

bearerAuth

Query parameters

Response

200400401500

Successfully retrieved a list of messages

Body

application/json

has_more*boolean

data*array of EmailMessageTransactional (object)

Request

JavaScriptCurl

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

Response

{
  "has_more": false,
  "data": [
    {
      "id": 42,
      "from": "Postman <[e-mail]>",
      "recipient": "[e-mail]",
      "params": {
        "body": "Hello World",
        "from": "Postman <[e-mail]>",
        "subject": "Hello World",
        "reply_to": "[e-mail]"
      },
      "attachments_metadata": [
        {
          "fileName": "text",
          "fileSize": 0,
          "hash": "text"
        }
      ],
      "status": "UNSENT",
      "error_code": "text",
      "error_sub_type": "text",
      "created_at": "2024-04-28T13:19:24.875Z",
      "updated_at": "2024-04-28T13:19:24.875Z",
      "accepted_at": "2024-04-28T13:19:24.875Z",
      "sent_at": "2024-04-28T13:19:24.875Z",
      "delivered_at": "2024-04-28T13:19:24.875Z",
      "opened_at": "2024-04-28T13:19:24.875Z"
    }
  ]
}

Response Format

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.

Supported Query Parameters

Limit

You can specify the number of emails to return per page using the limit query parameter. The default value is 10, the minimum value is 1, and the maximum value is 1000.

Offset

You can specify the number of emails to skip using the offset query parameter. The default value is 0.

Filtering

We currently support the following filters:

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

• tag: return emails with the specified tag. This is a user-defined tag that is created when the email is sent. For more information, see this section

• created_at: return emails created within the specified time range; this roughly corresponds to the time when 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:

• gt: greater than

• gte: greater than or equal to

• lt: less than

• lte: less than or equal to

Sorting

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.

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.

Example Queries

GET /transactional/email

Returns the first 10 emails sorted by created_at in descending order

GET /transactional/email?limit=20&offset=10

Returns the next 20 emails sorted by created_at in descending order

GET /transactional/email?status=DELIVERED

Returns the first 10 emails with status DELIVERED sorted by created_at in descending order

GET /transactional/email?created_at[gt]=2023-05-10T03:03:54.163Z

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 /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.

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.