Postman Guide
Go to Postman v1
  • 🥳About Postman v1 (Postman Legacy)
  • Campaign Guide - General
    • 🚀How to send a campaign?
      • ☝️Before You Start
        • Demo Mode
  • Campaign Guide - Email
    • 📧Email Campaigns - Basics
      • How do I send an email campaign?
      • Scheduled Sending
      • Bounced Emails and Halted Campaigns
      • Email Statistics
      • Formatting your Message Template
      • Variable Fields
      • Unique URL Link per Recipient
      • Pasting Content from Microsoft Word
      • Manage your Unsubscriptions
      • Understanding Unsubscriptions
    • 🔐Sending Password-Protected Emails
      • Tutorial
      • Template Editor
  • Campaign Guide - SMS
    • 📲SMS Campaigns - Basics
      • Before Starting Out
      • Summary of Costs
    • 🪜SMS Onboarding Overview
      • Step 1: Sender ID Registration
      • Step 2: Sign up for a Twilio account
      • Step 3: Set up your Twilio account
      • Step 4: Configure Your Twilio Account
        • What if I need to buy a phone number?
      • Step 5: Send a Test Message on Twilio
      • Step 6: Fill in your Twilio credentials in Postman!
        • How do I send a campaign with my saved SMS credentials?
    • 🤔What else do I need to know about sending SMSes?
      • More about Sender ID registration
      • Can I see the send status of my campaign?
      • How can I configure my SMS send rate?
      • Sending an SMS to a Foreign Number
      • SMS Best Practices
      • Useful Twilio Links
  • Campaign Guide - Telegram
    • 🤖Telegram Campaigns - Basics
      • How do I set up Telegram to send my campaigns?
      • Add Telegram Bot Token in Postman
      • Instructions for Recipient Onboarding
      • Use the Bot in the Campaign
      • Telegram Formatting
      • Telegram Bot Statistics
  • Email API Guide
    • 📖Overview
      • IM8 Policies
      • Connecting your Intranet Application
      • API Response Formats
    • 🗝️Email API Key Management
      • Bearer Authentication
      • Generate your email API Key
      • Rotate your email API Key
    • 📨Programmatic Email API
      • Getting Started
      • Comparison with AMR
      • SG-Mail Whitelisting
      • Custom From Address
      • Tracking Email Status
      • Send Email API
        • From Name and From Address
        • CC and BCC
        • Recipient Blacklist
        • Email Tagging and Classification
        • Email Body
          • Embedding Images
            • Linked Images
            • Content-ID Images
        • Attachments
        • Rate Limit
      • Get Email by ID API
      • List Emails API
    • 📨Programmatic GovSG WhatsApp API
      • Getting Started
      • Tracking Message Status
      • Get Available Templates API
      • Send Message API
      • Get Message by ID API
      • List Messages API
    • 🎓Frequently Asked Questions
  • FAQ
    • 📶Service Status
    • For Recipients
      • Check Email Authenticity
    • For Senders
      • Messaging Channel Comparison
      • Cost Breakdown
  • Legal
    • Terms & Conditions
    • Privacy Policy
  • Contact Us
  • GitHub
Powered by GitBook
On this page
  • Overview
  • Request body for transactional emails
  • Authorisation
  • Body
  • Response body
  • Example API Call
  • API Response
  • Status Code

Was this helpful?

  1. Email API Guide
  2. Programmatic Email API

Send Email API

How to send emails via Postman's email API

PreviousTracking Email StatusNextFrom Name and From Address

Last updated 8 months ago

Was this helpful?

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 . The latter is required for .

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

Authorisation

Bearer Token

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":"hello@example.com"

items string

`cc` example
"cc":["cc-recipient@email.com"]

items string

`bcc` example
"bcc":["bcc-recipient@email.com"]

`from` example
"from":"Your Agency <your_agency@agency.gov.sg>"

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":"hello@example.com"

This field accepts one of the following values:

  • URGENT

  • FOR_ACTION

  • FOR_INFO

`classification` example
"classification":"FOR_ACTION"

`tag` example
"tag":"Greetings v2"

attachments

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

Response body

Send email response example
{
  "id": 42,
  "from": "Postman <info@mail.postman.gov.sg>",
  "recipient": "hello@example.com",
  "cc":["cc-recipient@email.com"],
  "bcc":["bcc-recipient@email.com"],
  "params": {
    "body": "Hello there, this is the Postman team.",
    "from": "Postman <info@mail.postman.gov.sg>",
    "subject": "Hello There",
    "reply_to": "hello@example.com"
  },
  "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.

`id` example
"id":"42"

from string

`from` example
"from":"Your Agency <your_agency@agency.gov.sg>"

If the from attribute is not specified in your request, the response body will reflect the From address as Postman <info@mail.postman.gov.sg>

`from` default example
"from":"Postman <info@mail.postman.gov.sg>"

recipient string

The recipient that was specified in your request body

 "recipient": "hello@example.com"

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 <info@mail.postman.gov.sg>",
    "subject": "Hello There",
    "reply_to": "hello@example.com"

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 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 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="recipient@email.com"' \

This is the minimum required request body to send an email. The email will be sent from Postman.gov.sg <info@mail.postman.gov.sg>.

API Response

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:

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

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

Authorisation to Legacy Postman's API is performed with

.

The email address of the sender. If this field is omitted, the email will be sent from Postman <donotreply@mail.postman.gov.sg>. For more information, .

For more information, .

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

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

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

For general information about our API response formats, .

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 .

The recipient has been blacklisted. For more information, .

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

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

📨
multipart request
sending attachments
.
API key to authorise requests
cc array of string
bcc array of string
from string
see here
classification string
see here
tag string
see here
see here
see here
see here
this endpoint
see here
see here
HTML sanitisation
error_code nullable string
error_sub_type nullable string