> For the complete documentation index, see [llms.txt](https://guide.nomsa.gov.kh/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guide.nomsa.gov.kh/api-guide/programmatic-email-api/list-emails-api.md). # List Emails API This API allows you to retrieve previously sent emails. ```json curl --location 'https://api.nomsa.gov.kh/v1/transactional/email' \ --header 'Authorization: Bearer {{apikey}}' \ ``` #### Sample Response ```json { "has_more": true, "data": [ { "id": "95", "from": "NomsaSupportTeam ", "recipient": "recipient@gmail.com", "params": { "body": "

Hello there

", "from": "NomsaSupportTeam ", "subject": "Test two attachments" }, "attachments_metadata": [ { "hash": "d879061289e2ac51ef64bba9fcf3a3b1", "fileName": "nomsa_sample1.csv", "fileSize": 62 }, { "hash": "e2834551a0349c3473387d0f7d17d22f", "fileName": "nomsa_sample2.csv", "fileSize": 38 } ], "status": "OPENED", "error_code": null, "error_sub_type": null, "accepted_at": "2023-10-05T01:37:39.182Z", "sent_at": "2023-10-05T01:37:39.243Z", "delivered_at": "2023-10-05T01:37:40.771Z", "opened_at": "2023-10-05T01:37:54.786Z", "created_at": "2023-10-05T01:37:38.819Z", "updated_at": "2023-10-05T01:37:54.908Z", "classification": null, "tag": null, "cc": [], "bcc": [] }, { "id": "94", "from": "NomsaSupportTeam ", "recipient": "recipient@gmail.com", "params": { "body": "

Hello there

", "from": "NomsaSupportTeam ", "subject": "Test Attachments email" }, "attachments_metadata": [ { "hash": "e2834551a0349c3473387d0f7d17d22f", "fileName": "nomsa_sample1.csv", "fileSize": 38 } ], "status": "OPENED", "error_code": null, "error_sub_type": null, "accepted_at": "2023-10-05T01:34:27.818Z", "sent_at": "2023-10-05T01:34:27.888Z", "delivered_at": "2023-10-05T01:34:29.487Z", "opened_at": "2023-10-05T01:34:35.743Z", "created_at": "2023-10-05T01:34:27.463Z", "updated_at": "2023-10-05T01:34:35.827Z", "classification": null, "tag": null, "cc": [], "bcc": [] }, ] } ``` ## 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](https://guide.nomsa.gov.kh/api-guide/programmatic-email-api/get-email-by-id-api#example-response). * We support excluding the `params` field from the response object, see [this section](#excluding-params-field-from-response) 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](broken://pages/mGW96KeteoHpRe6PdAlA#email-status) * `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](#example-queries) * `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](https://en.wikipedia.org/wiki/ISO_8601). 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.