Mailercloud Email API - Help Guide

What is Mailercloud Email API?

The Mailercloud Email API allows you to send emails automatically from your application or website. You can define the sender, recipients, subject, email content, and even add attachments. This is useful for sending automated emails like order confirmations, password resets, or marketing emails.

How to Use the Email API?

To use this API, you need an API key for authentication.

Endpoint

POST https://email-api.mailercloud.com/email

Headers

Content-Type: application/json
Authorization: YOUR_API_KEY 

Normal Request Body

{
    "email": {
        "from": "[email protected]",
        "fromName": "John Doe",
        "replyTo": [
            "[email protected]",
            "[email protected]"
        ],
        "subject": "email subject",
        "text": "text body",
        "html": "html body",
        "recipients": {
            "to": [{
                "name": "Recipient1",
                "email": "abc12345"
            }, {
                "name": "Recipient2",
                "email": "[email protected]"
            }],
            "cc": [
                "[email protected]",
                "[email protected]"
            ],
            "bcc": [
                "[email protected]",
                "[email protected]"
            ]
        },
        "attachments": [{
            "name": "Attachment1",
            "url": "https://link/to/attachment/1"
        },{
            "name": "Attachment2",
            "url": "http://link/to/attachment/2"
        }]
    },
    "metadata": {
        "campaignType": "PROMOTIONAL", //Only allow TRANSACTIONAL or PROMOTIONAL
        "timestamp": "2018-01-25T10:24:16+0000",
        "messageId": "your-message-id", // unique id required
        "custom" : {
            "key1" : "val1",
            "key2" : "val2"
        }
    },
     "version": "1.0" //required
}

AMP Request Body

{
    "email": {
        "from": "[email protected]",
        "fromName": "John Doe",
        "replyTo": [
            "[email protected]",
            "[email protected]"
        ],
        "subject": "email subject",
        "text": "text body",
        "html": "html body",
        "amp_html" : "amp_body",
        "recipients": {
            "to": [{
                "name": "Recipient1",
                "email": "abc12345"
            }, {
                "name": "Recipient2",
                "email": "[email protected]"
            }],
            "cc": [
                "[email protected]",
                "[email protected]"
            ],
            "bcc": [
                "[email protected]",
                "[email protected]"
            ]
        },
        "attachments": [{
            "name": "Attachment1",
            "url": "https://link/to/attachment/1"
        },{
            "name": "Attachment2",
            "url": "http://link/to/attachment/2"
        }]
    },
    "metadata": {
        "campaignType": "PROMOTIONAL",  //Only allow TRANSACTIONAL or PROMOTIONAL
        "timestamp": "2018-01-25T10:24:16+0000",
        "messageId": "your-message-id", // unique id required
        "custom" : {
            "key1" : "val1",
            "key2" : "val2"
        }
    },
     "version": "2.0" // required
}

What Information is Required?

Response

Successful Response

When the email is sent successfully, the API returns:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "SUCCESS",
    "statusCode": 1000,
    "message": "NA"
}

Error Responses

Message Cannot Be Sent

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "ERROR",
    "statusCode": 9002,
    "message": "Daily email sending quota is over."
}

Payload Not Acceptable

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "status": "ERROR",
    "statusCode": 9022,
    "message": "Unsupported version",
    "supportedVersion": "1.0"
}

Status Codes and Their Meaning

Optional Fields

• Custom headers — email.headers, for example List-Unsubscribe or X-Order-Reference

• Inbox tracking — metadata.custom.inbox_tracking with metadata.custom.campaign_id

• Tags — metadata.custom.tags, up to 10, for filtering messages in the Activity list

• Content storage — metadata.custom.store_content: false for sensitive emails such as OTPs

• Duplicate protection — reusing a metadata.messageId within 24 hours does not send again and still returns success, so a timed-out request is safe to retry. The message ID is shown in the Activity list.

• Tracking — opens are tracked when your sending domain has a tracking domain configured. Click tracking is not available.

For the full field reference, see the Send Email API documentation.

One thing to note: messageId is described in the request-body samples as "unique id required", but it's optional — the server generates one if you leave it out. Worth correcting in both code comments while you're in there.