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
POST /v1/transactional/email/send
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)
"subject": "Hello World"
body string (mandatory)
"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":"[email protected]"
items string
"cc":["[email protected]"]
items string
"bcc":["[email protected]"]
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":"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":"[email protected]"
This field accepts one of the following values:
URGENT
FOR_ACTION
FOR_INFO
For more information, see here.
"classification":"FOR_ACTION"
This fields accept a user-defined string. For more information, see here.
"tag":"Greetings v2"
attachments
This field accepts a list of attachments and is only available via multipart requests. For more information, see here.
"attachments":/your/local/path-to-file
Response body
{
"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":"42"
from string
"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":"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": {
"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":[
{
"fileName":"text",
"fileSize":0,
"hash":"text"
}
],
status enum
The status of your message when you make a successful API call to our endpoints
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":"DELIVERED"
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
"status": "BOUNCED",
"error_code": "Invalid from address",
If your status is not UNSENT
, this field will be null
.
"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
"status": "BOUNCED",
"error_code": "Invalid from address",
"error_sub_type": "Hard Bounce",
If your status is not UNSENT
, this field will be null
.
"status": "DELIVERED",
"error_code": "null",
"error_sub_type": "null",
created_at string (date-time)
"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
.
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 be500
. (This is rare and unlikely to happen.)
Last updated
Was this helpful?