# List Emails API

```bash
GET /v1/transactional/email
```

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

### Request body for listing transactional emails

{% code title="eg. Response Body" overflow="wrap" %}

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

{% endcode %}

### Query Parameters

**limit** integer

max number of messages returned

***

**offset** integer

offset to begin returning messages from

{% code title="`offset` endpoint example" %}

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

{% endcode %}

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.&#x20;

This return emails with the specified status. For a list of possible values, see [this section](https://postman-v1.guides.gov.sg/email-api-guide/programmatic-email-api/tracking-email-status#email-status)

**item** enum

* `UNSENT`
* `ACCEPTED`
* `SENT`
* `BOUNCED`
* `DELIVERED`
* `OPENED`
* `COMPLAINT`

{% code title="`delivered` status example" %}

```bash
GET /transactional/email?status=DELIVERED
```

{% endcode %}

The example above returns the first 10 emails with the status `delivered`, soered by `created_at` in descending order.&#x20;

***

**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](https://en.wikipedia.org/wiki/ISO_8601). The list of supported operators are:

| Operators | Explanation              |
| --------- | ------------------------ |
| `gt`      | greater than             |
| `gte`     | greater than or equal to |
| `lt`      | less than                |
| `lte`     | less than or equal to    |

{% code title="`get` status time example" %}

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

{% endcode %}

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.

{% code title="`get` status example" overflow="wrap" %}

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

{% endcode %}

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.&#x20;

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.

{% code title="`sorted_by` example" overflow="wrap" %}

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

{% endcode %}

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

{% code title="Listing emails API response example" overflow="wrap" %}

```json
{
  "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"
    }
  ]
```

{% endcode %}

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](https://postman-v1.guides.gov.sg/email-api-guide/get-email-by-id-api#example-response). We support excluding the `params` field from the response object, see [this section](https://postman-v1.guides.gov.sg/email-api-guide/send-email-api#body) 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.