--- title: "Mailercloud Email API - Help Guide" description: "Mailercloud provides an easy way to send emails programmatically using our Email API. This guide will help you understand how to use it effectively." url: https://help.mailercloud.com/en/articles/155-mailercloud-email-api-help-guide collection: "API Platform" updated: 2026-10-29 language: en --- # Mailercloud Email API - Help Guide Mailercloud provides an easy way to send emails programmatically using our Email API. This guide will help you understand how to use it effectively. ## **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 ```javascript POST https://email-api.mailercloud.com/email ``` ### Headers ```javascript Content-Type: application/json Authorization: YOUR_API_KEY ``` ### Normal Request Body ```javascript { "email": { "from": "from@example.com", "fromName": "John Doe", "replyTo": [ "replyone@example.com", "replytwo@example.com" ], "subject": "email subject", "text": "text body", "html": "html 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", //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 ```javascript { "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", //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?**

Parameter

Type

Description

email.from

String

Sender’s email address

email.fromName

String

Sender’s name

email.replyTo

Array

Reply-to email addresses

email.subject

String

Email subject

email.text

String

Plain text version of the email. Optional: if you leave it out and send html, a plain-text version is generated from the HTML (see Plain-text version below).

email.html

String

HTML version of the email

email.recipients

Object

Contains recipient information (To, CC, BCC)

email.attachments

Array

Attach files to your email

## **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: ```javascript HTTP/1.1 200 OK Content-Type: application/json { "status": "SUCCESS", "statusCode": 1000, "message": "NA" } ``` ### Error Responses ### Message Cannot Be Sent ```javascript HTTP/1.1 200 OK Content-Type: application/json { "status": "ERROR", "statusCode": 9002, "message": "Daily email sending quota is over." } ``` ### Payload Not Acceptable ```javascript 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**

Status Code

Meaning

1000

Success

9001

Throttling error

9002

Message sending quota exceeded

9003

Authentication failure

9004

Recipient address not specified

9005

From field missing

9006

Soft bounce (temporarily deferred)

9007

Hard bounce

9008

Email reported as spam

9009

Email unsubscribed

9010

Email in suppression list

9011

Sender address not verified

9012

ESP rejected message

9013

Request to ESP expired

9014

ESP unavailable

9015

IP not whitelisted with ESP

9016

Subject field empty

9017

Invalid sender address

9018

Invalid email address

9019

Recipient's mailbox is full

9020

Error processing email at Private ESP

9021

Mailbox was not found on email server

9022

Unsupported or unknown version

9024

Authorization failure

9452

Message overloading

9512

Host email server not found

9999

Unknown error occurred

## 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](https://apidoc.mailercloud.com/api-reference/email/send-email) the Send Email API documentation.