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

Send Email by API CURL

curl --location 'https://api.nomsa.gov.kh/v1/transactional/email/send' \
--header 'Authorization: Bearer {{apikey}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "subject": "One time OTP",
    "body": "Hello here is your OTP: 145863 ",
    "recipient": "[email protected]"
}'

Request Body

{
    "id": "16",
    "from": "Nomsa <[email protected]>",
    "recipient": "[email protected]",
    "params": {
        "body": "Hello here is your OTP: 145863 ",
        "from": "Nomsa <[email protected]>",
        "subject": "One time OTP"
    },
    "attachments_metadata": null,
    "status": "ACCEPTED",
    "error_code": null,
    "error_sub_type": null,
    "accepted_at": "2023-10-04T13:17:34.407Z",
    "sent_at": null,
    "delivered_at": null,
    "opened_at": null,
    "created_at": "2023-10-04T13:17:34.017Z",
    "updated_at": "2023-10-04T13:17:34.407Z",
    "classification": null,
    "tag": null,
    "cc": [],
    "bcc": []
}

The user is strongly advised to save the id field (42 in the example), which is a unique identifier for the email. This 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.

The mandatory fields in the request body are as follows:

1. subject - The subject of the email.

2. body - The body of the email. For more information, see here.

3. recipient - The email address of the recipient. Currently, we only support sending email to a single recipient (i.e. cc and bcc are not supported).

The optional fields accepted by the endpoint are as follows:

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

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

3. classification - This field accepts one of the following values: URGENT, FOR_ACTION, and FOR_INFO. For more information, see here.

4. tag - This fields accept a user-defined string. For more information, see here.

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

See the screenshot below for an example of how some of these fields correspond to what an email recipient sees:

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. The recipient has been blacklisted. For more information, see here.

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

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