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": "[email protected]",
      "cc":["[email protected]"],
      "bcc":["[email protected]"],
      "classification":"FOR_ACTION",
      "tag":"Greetings v2"
      
    }),
});
const data = await response.json();

Authorisation

Authorisation to Legacy Postman's API is performed with .

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":"[email protected]"

cc array of string

items string

`cc` example

"cc":["[email protected]"]

bcc array of string

items string

`bcc` example

"bcc":["[email protected]"]

from string

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

`from` example

"from":"Your Agency <[email protected]>"

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":"[email protected]"

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 <[email protected]>",
  "recipient": "[email protected]",
  "cc":["[email protected]"],
  "bcc":["[email protected]"],
  "params": {
    "body": "Hello there, this is the Postman team.",
    "from": "Postman <[email protected]>",
    "subject": "Hello There",
    "reply_to": "[email protected]"
  },
  "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 <[email protected]>"

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

`from` default example

"from":"Postman <[email protected]>"

recipient string

The recipient that was specified in your request body

 "recipient": "[email protected]"

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 <[email protected]>",
    "subject": "Hello There",
    "reply_to": "[email protected]"

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="[email protected]"' \

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

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:

The request body is invalid because of missing mandatory fields or invalid field values. The error message will provide more details.
The recipient has been blacklisted. For more information, see here.
The user has exceeded the rate limit. For more information, see here.
The subject or the body of the email is empty after applying HTML sanitisation.
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.)

PreviousTracking Email Status NextFrom Name and From Address

Last updated 10 months ago

Was this helpful?