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 

Request Body

{
    "email": {
        "from": "from@example.com",
        "fromName": "John Doe",
        "replyTo": [
            "replyone@example.com",
            "replytwo@example.com"
        ],
        "subject": "email subject",
        "text": "text body",
        "html": "html body",
        "amp_html" : "amp_body",
        "recipients": {
            "to": [{
                "name": "Recipient1",
                "email": "abc12345"
            }, {
                "name": "Recipient2",
                "email": "abc@example.com"
            }],
            "cc": [
                "recipient_cc1@example.com",
                "recipient_cc2@example.com"
            ],
            "bcc": [
                "recipient_bcc1@example.com",
                "recipient_bcc2@example.com"
            ]
        },
        "attachments": [{
            "name": "Attachment1",
            "url": "https://link/to/attachment/1"
        },{
            "name": "Attachment2",
            "url": "http://link/to/attachment/2"
        }]
    },
    "metadata": {
        "campaignType": "PROMOTIONAL",
        "timestamp": "2018-01-25T10:24:16+0000",
        "messageId": "your-message-id",
        "custom" : {
            "key1" : "val1",
            "key2" : "val2"
        }
    },
     "version": "1.0"
}

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