Send Email API

How to send emails via Postman's 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.

Request body for transactional emails

Send email endpoint

POST /v1/transactional/email/send

Send email request example

const response = await fetch('/v1/transactional/email/send', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "subject": "Hello There",
      "body": "Hello there, this is the Postman team.",
      "recipient": "[e-mail]",
      "cc":["[e-mail]"],
      "bcc":["[e-mail]"],
      "classification":"FOR_ACTION",
      "tag":"Greetings v2"
      
    }),
});
const data = await response.json();

Authorisation

Authorisation to Legacy Postman's API is performed with HTTP Bearer Auth.

Bearer Token

API key to authorise requests.

Body

subject string (mandatory)

Example

"subject": "Hello World"

---

body string (mandatory)

`body` example

"body":"Hello World"

---

recipient string (mandatory)

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

`recipient` example

"recipient":"[e-mail]"

---

cc array of string

items string

`cc` example

"cc":["[e-mail]"]

---

bcc array of string

items string

`bcc` example

"bcc":["[e-mail]"]

---

from string

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

`from` example

"from":"Your Agency <[e-mail]>"

---

reply_to string

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.

`reply_to` example

"reply_to":"[e-mail]"

---

classification string

This field accepts one of the following values:

• URGENT

• FOR_ACTION

• FOR_INFO

For more information, see here.

`classification` example

"classification":"FOR_ACTION"

---

tag string

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

`tag` example

"tag":"Greetings v2"

---

attachments

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

`attachments` example

"attachments":/your/local/path-to-file

Response body

Send email response example

{
  "id": 42,
  "from": "Postman <[e-mail]>",
  "recipient": "[e-mail]",
  "cc":["[e-mail]"],
  "bcc":["[e-mail]"],
  "params": {
    "body": "Hello there, this is the Postman team.",
    "from": "Postman <[e-mail]>",
    "subject": "Hello There",
    "reply_to": "[e-mail]"
  },
  "attachments_metadata": [
    {
      "fileName": "text",
      "fileSize": 0,
      "hash": "text"
    }
  ],
  "status": "OPENED",
  "error_code": null,
  "error_sub_type": null,
  "created_at": "2024-08-27T08:38:40.359Z",
  "updated_at": "2024-08-27T08:38:40.359Z",
  "accepted_at": "2024-08-27T08:38:40.359Z",
  "sent_at": "2024-08-27T08:38:40.359Z",
  "delivered_at": "2024-08-27T08:38:40.359Z",
  "opened_at": "2024-08-27T08:38:40.359Z"
}

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

id string

id: a unique identifier for the email, generated by Postman.

Users are strongly encouraged to save the id of their messages.

The id 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.

`id` example

"id":"42"

---

from string

`from` example

"from":"Your Agency <[e-mail]>"

If the from attribute is not specified in your request, the response body will reflect the From address as Postman <[e-mail]>

`from` default example

"from":"Postman <[e-mail]>"

---

recipient string

The recipient that was specified in your request body

 "recipient": "[e-mail]"

---

params object

The parameters of body, from and subject as specified in your request body.

body string (mandatory)

from string

subject string (mandatory)

`params` default response example

  "params": {
    "body": "Hello there, this is the Postman team.",
    "from": "Postman <[e-mail]>",
    "subject": "Hello There",
    "reply_to": "[e-mail]"

---

attachments_metadata nullable array of object

fileName string

fileSize number

hash string

'attachments_metadata' response example

"attachments_metadata":[
    {
        "fileName":"text",
        "fileSize":0,
        "hash":"text"
    }
],

---

status enum

The status of your message when you make a successful API call to our endpoints

Status	Explanation
UNSENT	Initial state of a newly created transactional email
ACCEPTED	Email has been accepted by our email provider
SENT	The send request was successfully forwarded to our email provider Our email provider will attempt to deliver the message to the recipient's mail server
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 recipeint received the message and opened it in their email client
COMPLAINT	The email was successfully delivered to the reciepint's mail server, but the recipient marked it as spam

`status` default response

"status":"DELIVERED"

---

error_code nullable string

error_code string will be filled if the status of your email is BOUNCED

• Invalid from address

• From address has not been verified

• Blacklisted recipeint

`error_code` response example

"status": "BOUNCED",
"error_code": "Invalid from address",

If your status is not UNSENT, this field will be null.

null `error_code` response example

"status": "DELIVERED",
"error_code": "null",

---

error_sub_type nullable string

error_sub_type string will appear if the status of your email is BOUNCED

• Hard Bounce

• Soft Bounce

• Complaint

`error_sub_type` response example

"status": "BOUNCED",
"error_code": "Invalid from address",
"error_sub_type": "Hard Bounce",

If your status is not UNSENT, this field will be null.

null `error_code` response example

"status": "DELIVERED",
"error_code": "null",
"error_sub_type": "null",

---

created_at string (date-time)

`created_at` response example

"created_at": "2023-05-10T03:03:55.406Z"

---

updated_at nullable string (date-time)

---

accepted_at nullable string (date-time)

Will appear if the status of your message goes through ACCEPTED

---

sent_at nullable string (date-time)

Will appear if the status of your message goes through SENT

---

delivered_at nullable string (date-time)

Will appear if the status of your message goes through DELIVERED

---

opened_at nullable string (date-time)

Will appear if the status of your message goes through OPENED

---

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.)