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", // optional; generated by the server if omitted
        "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", // optional; generated by the server if omitted
        "custom" : {
            "key1" : "val1",
            "key2" : "val2"
        }
    },
     "version": "2.0" // required
}

What Information is Required?

Plain-text version

Every message is sent with both a plain-text part and your HTML (multipart/alternative), so it reads well in every mail client.

• If you send email.text, it is used exactly as you sent it.

• If you send only email.html, the plain-text part is generated from it: headings and paragraphs become lines, list items become bullets, and links keep their address as "Link text (https://…)". HTML with no readable text, such as an image-only email, is sent as HTML only.

• To send an HTML-only message as HTML only, set metadata.custom.auto_text to false. Any email.text you include is still sent.

• Over SMTP relay, the same control is the mld-track-auto-text header (false to turn generation off).

In Transactional → Activity, open a message to see the plain-text part that was actually sent (yours or the generated one) under Plain text, and the complete message as delivered under Raw source. For a message sent to several recipients, each recipient’s row shows that recipient’s own content and raw source.

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

• Plain-text generation — metadata.custom.auto_text: false to send an HTML-only message without a generated plain-text part (see Plain-text version above)

• 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.