# Send 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](https://swagger.io/docs/specification/describing-request-body/multipart-requests/). The latter is required for [sending attachments](https://postman-v1.guides.gov.sg/email-api-guide/programmatic-email-api/send-email-api/attachments). ## Request body for transactional emails {% code title="Send email endpoint" %} ```bash POST /v1/transactional/email/send ``` {% endcode %} {% code title="Send email request example" overflow="wrap" fullWidth="false" %} ```javascript const response = await fetch('/v1/transactional/email/send', { method: 'POST', headers: { "Authorization": "Bearer ", "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(); ``` {% endcode %} ## Authorisation Authorisation to Legacy Postman's API is performed with [HTTP Bearer Auth](#user-content-fn-1)[^1][. ](https://postman-v1.guides.gov.sg/email-api-guide/api-key-management/bearer-authentication) **Bearer Token** [API key to authorise requests](https://postman-v1.guides.gov.sg/email-api-guide/api-key-management/generate-your-api-key). ## Body **subject** string (mandatory) {% code title="Example" overflow="wrap" %} ```json "subject": "Hello World" ``` {% endcode %} *** **body** string (mandatory) {% code title="`body` example" overflow="wrap" %} ```json "body":"Hello World" ``` {% endcode %} *** **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). {% code title="`recipient` example" overflow="wrap" %} ```json "recipient":"hello@example.com" ``` {% endcode %} *** [**cc** array of string](https://postman-v1.guides.gov.sg/email-api-guide/programmatic-email-api/send-email-api/cc-and-bcc#/what-is-cc-and-bcc) **items** string {% code title="`cc` example" overflow="wrap" %} ```json "cc":["cc-recipient@email.com"] ``` {% endcode %} *** [**bcc** array of string](https://postman-v1.guides.gov.sg/email-api-guide/programmatic-email-api/send-email-api/cc-and-bcc#/what-is-cc-and-bcc) **items** string {% code title="`bcc` example" overflow="wrap" %} ```json "bcc":["bcc-recipient@email.com"] ``` {% endcode %} *** [**from** string](https://postman-v1.guides.gov.sg/email-api-guide/programmatic-email-api/send-email-api/from-name-and-from-address) The email address of the sender. If this field is omitted, the email will be sent from Postman ``. For more information, [see here](https://postman-v1.guides.gov.sg/email-api-guide/programmatic-email-api/send-email-api/from-name-and-from-address). {% code title="`from` example" %} ```json "from":"Your Agency " ``` {% endcode %} ![](https://4126954886-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MAQH3DF49Lq0AJudrbF%2Fuploads%2Fgit-blob-d1cf44af465d808a08e79bd4e17b426e3bc30e1a%2Femail-fields.png?alt=media) *** **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. {% code title="`reply-to` example" overflow="wrap" %} ```json "reply-to":"hello@example.com" ``` {% endcode %} *** [**classification** string](https://postman-v1.guides.gov.sg/email-api-guide/programmatic-email-api/send-email-api/email-tagging-and-classification#/email-classification) This field accepts one of the following values: * `URGENT` * `FOR_ACTION` * `FOR_INFO` For more information, [see here](https://postman-v1.guides.gov.sg/email-api-guide/programmatic-email-api/send-email-api/email-tagging-and-classification). {% code title="`classification` example" overflow="wrap" %} ```json "classification":"FOR_ACTION" ``` {% endcode %} *** [**tag** string](https://postman-v1.guides.gov.sg/email-api-guide/programmatic-email-api/send-email-api/email-tagging-and-classification#/email-tagging) This fields accept a user-defined string. For more information, [see here](https://postman-v1.guides.gov.sg/email-api-guide/programmatic-email-api/send-email-api/email-tagging-and-classification). {% code title="`tag` example" overflow="wrap" %} ```json "tag":"Greetings v2" ``` {% endcode %} *** **attachments** This field accepts a list of attachments and is only available via multipart requests. For more information, [see here](https://postman-v1.guides.gov.sg/email-api-guide/programmatic-email-api/send-email-api/attachments). {% code title="`attachments` example" %} ```json "attachments":/your/local/path-to-file ``` {% endcode %} ### Response body {% code title="Send email response example" %} ```json { "id": 42, "from": "Postman ", "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 ", "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" } ``` {% endcode %} 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](https://postman-v1.guides.gov.sg/email-api-guide/programmatic-email-api/get-email-by-id-api). {% code title="`id` example" %} ```json "id":"42" ``` {% endcode %} *** **from** string {% code title="`from` example" %} ```json "from":"Your Agency " ``` {% endcode %} If the `from` attribute is not specified in your request, the response body will reflect the From address as `Postman ` {% code title="`from` default example" %} ```json "from":"Postman " ``` {% endcode %} *** **recipient** string The recipient that was specified in your request body {% code title="" %} ```json "recipient": "hello@example.com" ``` {% endcode %} *** **params** object The parameters of `body`, `from` and `subject` as specified in your request body. **body** string (mandatory) **from** string **subject** string (mandatory) {% code title="`params` default response example" %} ```json "params": { "body": "Hello there, this is the Postman team.", "from": "Postman ", "subject": "Hello There", "reply_to": "hello@example.com" ``` {% endcode %} *** **attachments\_metadata** nullable array of object **fileName** string **fileSize** number **hash** string {% code title="'attachments\_metadata' response example" overflow="wrap" %} ```json "attachments_metadata":[ { "fileName":"text", "fileSize":0, "hash":"text" } ], ``` {% endcode %} *** **status** enum The status of your message when you make a successful API call to our endpoints
StatusExplanation
UNSENTInitial state of a newly created transactional email
ACCEPTEDEmail 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

BOUNCEDThe recipient's mail server rejected the email
DELIVEREDThe email provider has successfully delivered the email to the recipient;s mail server
OPENEDThe recipeint received the message and opened it in their email client
COMPLAINTThe email was successfully delivered to the reciepint's mail server, but the recipient marked it as spam
{% code title="`status` default response" %} ```json "status":"DELIVERED" ``` {% endcode %} *** [**error\_code** nullable string](https://postman-v1.guides.gov.sg/email-api-guide/tracking-email-status#error-codes-and-error-subtype) `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` {% code title="`error_code` response example" %} ```json "status": "BOUNCED", "error_code": "Invalid from address", ``` {% endcode %} If your status **is not** `UNSENT`, this field will be `null`. {% code title="null `error_code` response example" %} ```json "status": "DELIVERED", "error_code": "null", ``` {% endcode %} *** [**error\_sub\_type** nullable string](https://postman-v1.guides.gov.sg/email-api-guide/tracking-email-status#error-codes-and-error-subtype) `error_sub_type` string will appear if the **status** of your email is `BOUNCED` * `Hard Bounce` * `Soft Bounce` * `Complaint` {% code title=" `error_sub_type` response example" %} ```json "status": "BOUNCED", "error_code": "Invalid from address", "error_sub_type": "Hard Bounce", ``` {% endcode %} If your status **is not** `UNSENT`, this field will be `null`. {% code title="null `error_code` response example" %} ```json "status": "DELIVERED", "error_code": "null", "error_sub_type": "null", ``` {% endcode %} *** **created\_at** string (date-time) {% code title="`created_at` response example" overflow="wrap" %} ```json "created_at": "2023-05-10T03:03:55.406Z" ``` {% endcode %} *** **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 ```bash 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="

Hello there

"' \ --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 `. ## API Response For general information about our API response formats, [see here](https://postman-v1.guides.gov.sg/email-api-guide/overview/api-response-formats). ### Status Code In the event of a successful request, the response status code will be `201 Created`. {% hint style="info" %} 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](https://github.com/opengovsg/postmangovsg-guide/blob/main/api-guide/programmatic-email-api/programmatic-email-api/get-email-by-id-api.md). {% endhint %} 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](https://postman-v1.guides.gov.sg/email-api-guide/programmatic-email-api/send-email-api/recipient-blacklist). 3. The user has exceeded the rate limit. For more information, [see here](https://postman-v1.guides.gov.sg/email-api-guide/programmatic-email-api/send-email-api/rate-limit). 4. The subject or the body of the email is empty after applying [HTML sanitisation](https://postman-v1.guides.gov.sg/email-api-guide/programmatic-email-api/email-body#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.) [^1]: