Send Email API

This section of the guide contains information on how our API to send email works. For detailed information, please follow the links at the end of this page.


This POST endpoint accepts a request body that contains information about the email to be sent. Each successful request to this endpoint will send a single email.

The request body can either be JSON or multipart request. The latter is required for sending attachments.

Request Body

The mandatory fields in the request body are as follows:

  1. subject - The subject of the email.

  2. body - The body of the email. For more information, see here.

  3. recipient - The email address of the recipient. Currently, we only support sending email to a single recipient (i.e. cc and bcc are not supported).

The optional fields accepted by the endpoint are as follows:

  1. from - The email address of the sender. If this field is omitted, the email will be sent from <>. For more information, see here.

  2. reply_to - This sets the "Reply-To" email address, which allows sending an email from one email address and telling the recipients to reply to another address. If this field is omitted, it will default to the sender's email address.

  3. classification - This field accepts one of the following values: URGENT, FOR_ACTION, and FOR_INFO. For more information, see here.

  4. tag - This fields accept a user-defined string. For more information, see here.

  5. attachments - This field accepts a list of attachments and is only available via multipart requests. For more information, see here.

See the screenshot below for an example of how some of these fields correspond to what an email recipient sees:

Example API Call

curl --location --request POST '' \
--header 'Authorization: Bearer your_api_key' \
--form 'subject="Test email"'
--form 'body="<p>Hello <b>there</b></p>"' \
--form 'recipient=""' \

This is the minimum required request body to send an email. The email will be sent from <>.

API Response

For general information about our API response formats, see here.

Status Code

In the event of a successful request, the response status code will be 201 Created.

Sending emails is an asynchronous process. After receiving your API call, Postman will attempt to send the email via our email service provider. As such, a successful API request simply means the request has been made successfully. To return a response to each API call promptly, there is not enough time to ensure that your message has been sent or delivered successfully. To check on the status of your email, you should call this endpoint.

For unsuccessful requests, we will provide an appropriate status code and error message to indicate the reason for the failure.

A (non-exhaustive) list of reasons why a request may fail is as follows:

  1. The request body is invalid because of missing mandatory fields or invalid field values. The error message will provide more details.

  2. The recipient has been blacklisted. For more information, see here.

  3. The user has exceeded the rate limit. For more information, see here.

  4. The subject or the body of the email is empty after applying HTML sanitisation.

  5. Internal server error. Unlike the previous reasons (which have a 4xx error code), the error code for this will be 500. (This is rare and unlikely to happen.)

Response JSON Object

For the API call illustrated above, the response JSON object would be as follows:

  "id": "42",
  "from": " <>",
  "recipient": "",
  "params": {
    "body": "<p>Hello <b>there</b></p>",
    "from": " <>",
    "subject": "Test email",
    "reply_to": ""
  "attachments_metadata": null,
  "status": "ACCEPTED",
  "error_code": null,
  "error_sub_type": null,
  "created_at": "2023-05-10T03:03:55.406Z",
  "updated_at": "2023-05-10T03:03:55.406Z",
  "accepted_at": "2023-05-10T03:03:55.406Z",
  "sent_at": null,
  "delivered_at": null,
  "opened_at": null,
  "classification": null,
  "tag": null

The user is strongly advised to save the id field (42 in the example), which is a unique identifier for the email. This can be used to check the status of the email via a separate endpoint that will return a similar JSON object. For more information, see here.

For more detailed information, you can explore the links in the sidebar.

Last updated