API Documentation
Postman has 2 types of API. Programmatic and Campaigns API. Depending on your use case, you may chose either of these.
Type | Programmatic Email API | Campaigns API* |
|---|---|---|
How it works | Sends to one recipient at a time | Sends to multiple recipients at once |
Examples use cases | Application Approval, Email Receipt, Reminder to pay fine | Mass event invitation, mass broadcast of a policy update |
*Campaigns API is still a work in progress so you may not find the full documentation on this. However, you may still refer to the endpoints on our Swagger Docs.
The use of the API is limited to non-password protected campaigns only.
This guide covers how to send emails using either the programmatic API.
You may try out the other endpoints listed in the swagger docs.
Swagger UI
Access our swagger docs for all the API endpoints available
We have since renamed our transactional API to programmatic API to better reflect what it does. However, this change has not been applied to the specific endpoints yet. You may find that the programmatic endpoints are still listed as
/transactional/ in our Swagger Docs. Make sure that you have generated the bearer token as you will need it to be passed to all API calls.
Postman uses conventional API Responses Codes to indicate the success or failure of an API request.
Response codes do not tell you the delivery status or if your emails are sent. You should be calling the status endpoint.
Code | Description |
|---|---|
201 | Created. The message is being sent. |
400 | Bad Request. Failed parameter validations, message is malformed, or attachments are rejected. |
401 | Unauthorised |
403 | Forbidden. Request violates firewall rules. |
413 | Number of attachments or size of attachments exceeded limit. |
429 | Rate limit exceeded. Too many requests. |
500 | Internal Server Error.
This includes error such as custom domain passed email validation but is incorrect; see here. |
Usage of the programmatic API is recommended if you need the following features:
- Single API call to send email
- File attachments (more on this below)
Note the following if you are using the programmatic email API:
- Email template will not be applied
- No variable substitution
The default rate limit of our API is 10 message/s
This is configurable so if you think we require higher rate limit, feel free to reach out to us.
Postman API allows the sending of attachment. Here are a few things to note:
- Attachment should not exceed 2MB in size
- You can only attach a maximum of 2 attachments per email
- Attachment format must be within the list of file types (see the full list below).
- This is only available to users who has configured custom domain. ie. sending from your own domain. If you'd like to configure the emails to send from your own domain, reach out to us to find out more details.
Without attachments
curl --location --request POST 'https://api.postman.gov.sg/v1/transactional/email/send' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer your_api_key' \
--data-raw '{
"subject": "Test email",
"body": "<p>Hello <b>there</b></p>",
"recipient": "[email protected]"
}'
With 1 attachment
curl --location --request POST 'https://api.postman.gov.sg/v1/transactional/email/send' \
--header 'Authorization: Bearer your_api_key' \
--form 'body="<p>Hello <b>there</b></p>"' \
--form 'recipient="[email protected]"' \
--form '[email protected]"/your/local/path-to-file"' \
--form 'subject="Test email"'
With multiple attachments
curl --location --request POST 'https://api.postman.gov.sg/v1/transactional/email/send' \
--header 'Authorization: Bearer your_api_key' \
--form 'body="<p>Hello <b>there</b></p>"' \
--form 'recipient="[email protected]"' \
--form '[email protected]"/your/local/path-to-file-1"' \
--form '[email protected]"/your/local/path-to-file-2"' \
--form 'subject="Test email"'
You can get the delivery status of the emails sent using the
GETendpoint /transactional/email.
Below is a list of statuses you might receive and what it means.Status | Definition |
|---|---|
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 |
If you prefer to use Postman Programmatic SMS API, you may find the Programmatic SMS API endpoints on our Swagger Docs.
Our Campaigns API is still currently work in progress. You may find the endpoints for campaign based API in our Swagger Docs but it is not actively maintained so we recommend that you speak with us regarding your use case as you try it out.
Last modified 5d ago