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.

Overview

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.

Send a transactional email

POST/v1/transactional/email/send

Authorization

bearerAuth

Body

application/jsonmultipart/form-data

subject*string

body*string

recipient*string

ccarray of string

bccarray of string

fromstring

reply_tostring

classificationenum

URGENTFOR_ACTIONFOR_INFO

tagstring

Response

201400401403413429500

Created. The message is being sent.

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/send', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "subject": "text",
      "body": "text",
      "recipient": "text"
    }),
});
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-27T21:57:12.214Z",
  "updated_at": "2024-04-27T21:57:12.214Z",
  "accepted_at": "2024-04-27T21:57:12.214Z",
  "sent_at": "2024-04-27T21:57:12.214Z",
  "delivered_at": "2024-04-27T21:57:12.214Z",
  "opened_at": "2024-04-27T21:57:12.214Z"
}

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 Postman.gov.sg <[e-mail]>. 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 'https://api.postman.gov.sg/v1/transactional/email/send' \
--header 'Authorization: Bearer your_api_key' \
--form 'subject="Test email"'
--form 'body="<p>Hello <b>there</b></p>"' \
--form 'recipient="[e-mail]"' \

This is the minimum required request body to send an email. The email will be sent from Postman.gov.sg <[e-mail]>.

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": "Postman.gov.sg <[e-mail]>",
  "recipient": "[e-mail]",
  "params": {
    "body": "<p>Hello <b>there</b></p>",
    "from": "Postman.gov.sg <[e-mail]>",
    "subject": "Test email",
    "reply_to": "[e-mail]"
  },
  "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.