Email Sending API

Learn how to send emails via our API.

Maileroo's Email Sending API allows you to send emails via HTTP requests. This API is ideal for developers who want to integrate Maileroo into their applications and automate their email sending process.

The Email Sending API is a RESTful API that uses JSON as its response format. It only supports HTTPS and redirects all HTTP requests to HTTPS. All requests must be authenticated using an API key.

Authentication

All requests must be authenticated using a sending (API) key. You can create a sending key in the Sending Keys section of the Dashboard.

To authenticate a request, you must include your sending key in the X-API-Key header of the request. The value of the header must be your sending key.

1. CREATE EMAIL FROM SCRATCH

You can create an email from scratch by sending a POST request to the API endpoint. Your request must include the sender's email address, the recipient's email address, the email subject, and the email body in either HTML or plain text format (or both).

API Endpoint

The API endpoint for sending emails is:

Method: POST

Content Type: multipart/form-data

Request Body

The request body must be a multipart/form-data object containing the following fields:

from Sender's email address
to Comma-separated list of recipient email addresses
cc (Optional) Comma-separated list of CC email addresses
bcc (Optional) Comma-separated list of BCC email addresses
reply_to (Optional) Comma-separated list of reply-to email addresses
subject Email subject
html (Optional / Required) Email body in HTML format.
plain (Optional / Required) Email body in plain text format.
attachments (Optional) An array of file attachments
inline_attachments (Optional) An array of inline file attachments
reference_id (Optional) A 24-character hexadecimal string to identify the email
tags (Optional) A JSON object containing the tag key-value pairs
tracking (Optional) Either yes or no. By default, account settings are used.

2. CREATE EMAIL FROM TEMPLATE

You can create an email from a template by sending a POST request to the API endpoint. Your request must include the sender's email address, the recipient's email address, the email subject, the template ID and the template data.

API Endpoint

The API endpoint for sending emails is:

Method: POST

Content Type: multipart/form-data

Request Body

The request body must be a multipart/form-data object containing the following fields:

from Sender's email address
to Comma-separated list of recipient email addresses
cc (Optional) Comma-separated list of CC email addresses
bcc (Optional) Comma-separated list of BCC email addresses
reply_to (Optional) Comma-separated list of reply-to email addresses
subject Email subject
template_id (Required) The ID of the template you want to use
template_data (Optional) A JSON object containing the data to be used in the template (string values only)
attachments (Optional) An array of file attachments
inline_attachments (Optional) An array of inline file attachments
reference_id (Optional) A 24-character hexadecimal string to identify the email
tags (Optional) A JSON object containing the tag key-value pairs
tracking (Optional) Either yes or no. By default, account settings are used.

Notes

1. For an email generated from scratch, the html and plain fields are both optional, but at least one of them must be present. If both are present, our API will combine them to create a multipart/alternative email.


2. You may use the following formats for the email addresses:

example@maileroo.com
"Name" <example@maileroo.com>
<example@maileroo.com>


3. You can add an inline image to the email by using the inline_attachments field. You can then reference the image in the html field using the cid attribute (e.g. <img src="cid:my-image.png">). This may also work with template emails.

4. You can assign a Reference ID to each email you send. This Reference ID will be included in the webhook events, allowing you to track the delivery status of each email. In addition to that, you can also include tags with each email, which will also be included in the webhook events. A Reference ID must contain 24 hexadecimal characters, and the tags must be provided as a JSON object with string values only. For more information on webhooks, please see the Webhooks documentation.

5. The total size of all attachments must not exceed 23 MB.

Response Body

The response body is a JSON object containing the following fields:

success A boolean indicating whether the request was successful or not
message A string containing the error message if the request failed or a success message if the request was successful

HTTP Response Codes

The API returns the following response codes:

200 The request was successful. Check the response body for more details.
401 You have used an invalid API key. Please check your API key and try again.
400 The request was invalid. Check the response body for more details.

Code Examples

Please download the ZIP file below to get code examples in CURL, PHP, Golang, Python, and Node.js.

Download Code Examples