Get Email by ID API

This API allows you to retrieve metadata about a specific email sent via our API via its id. The most common use case for this API is to check on the status of an email.

How It Works

To use this API, you must save the id field in the response returned when making an API call to send the email. For more information, see this section.

Get transactional email by ID

GET/v1/transactional/email/{emailId}

Authorization

bearerAuth

Path parameters

emailId*string

Response

200400401404500

Successfully retrieved transactional email with corresponding ID

Body

application/json

idstring

fromstring

recipientstring

paramsobject

attachments_metadatanullable array of object

statusenum

• UNSENT - initial state of a newly created transactional email (this status is not returned in the course of a successful request to send an email)
• ACCEPTED - email has been accepted by our email provider (this status is returned in the course of a successful request to send an email)
• SENT - the send request was successfully forwarded to our email provider and our email provider will attempt to deliver the message to the recipient’s mail server (API user can check this and all subsequent statuses via the /transactional/email/{emailId} endpoint)
• BOUNCED - the recipient's mail server rejected the email
• DELIVERED - the email provider has successfully delivered the email to the recipient's mail server
• OPENED - the recipient received the message and opened it in their email client
• COMPLAINT - the email was successfully delivered to the recipient’s mail server, but the recipient marked it as spam

UNSENTACCEPTEDSENTBOUNCEDDELIVEREDOPENEDCOMPLAINT

error_codenullable string

error_sub_typenullable string

created_atstring (date-time)

updated_atnullable string (date-time)

accepted_atnullable string (date-time)

sent_atnullable string (date-time)

delivered_atnullable string (date-time)

opened_atnullable string (date-time)

Request

JavaScriptCurl

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

Response

{
  "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-27T20:55:23.089Z",
  "updated_at": "2024-04-27T20:55:23.089Z",
  "accepted_at": "2024-04-27T20:55:23.089Z",
  "sent_at": "2024-04-27T20:55:23.089Z",
  "delivered_at": "2024-04-27T20:55:23.089Z",
  "opened_at": "2024-04-27T20:55:23.089Z"
}

Example Response

{
  "id": "42",
  "from": "Postman.gov.sg <[e-mail]>",
  "recipient": "[e-mail]",
  "params": {
    "body": "Hello World",
    "from": "Postman.gov.sg <[e-mail]>",
    "subject": "Hello World",
    "reply_to": "[e-mail]"
  },
  "attachments_metadata": [
    {
      "fileName": "example.pdf",
      "fileSize": 1240,
      "hash": "8743b52063cd84097a65d1633f5c74f5"
    }
  ],
  "status": "DELIVERED",
  "error_code": null,
  "error_sub_type": null,
  "created_at": "2023-05-10T03:03:54.163Z",
  "updated_at": "2023-05-10T03:05:00.000Z",
  "accepted_at": "2023-05-10T03:03:55.406Z",
  "sent_at": "2023-05-10T03:04:01.912Z",
  "delivered_at": "2023-05-10T03:05:00.000Z",
  "opened_at": null,
  "classification": "FOR_ACTION",
  "tag": "hello world"
}

Limitations

We currently do not support pushing webhooks to your server when the status of an email changes. We are exploring the possibility of providing more email analytics, such as monthly reports aggregating statistics about email deliverability grouped based on user-defined tags. For more information, see this section.