Skip to main content

Send Bulk Emails

In addition to sending individual emails, Maileroo allows you to send bulk emails by sending a POST request with a JSON payload. You can either supply a template ID or provide the full email content with full templating functionality. This is particularly useful for sending newsletters, marketing campaigns, or any other type of mass communication.

Endpoint

POST https://smtp.maileroo.com/api/v2/emails/bulk

Request Body

subject string required

The email subject line, limited to 255 characters. It also supports simple, dynamic variables from template data (for example, {{ first_name }}).


messages array required

An array of MesssageObject items, where each item represents a single email to be sent. Each email can have its own from, to, cc, bcc, reply_to, reference_id and template_data. The maximum number of items in the messages array is 500.


template_id integer

You must include either plain, html, or template_id in the request body. If using template_id, it must reference a valid template in your Maileroo account.

Required when plain and html are not provided.


plain string

Email body in plain text format. Either html or plain is required. Templating support is available in plain text emails, allowing you to use variables and expressions.

Required when html or template_id are not provided.


html string

Email body in HTML format. Either html or plain is required. Templating support is available in HTML emails, allowing you to use variables and expressions.

Required when plain or template_id are not provided.


tracking boolean

Enable or disable open/click tracking for the email. If not specified, defaults to account settings.


tags object (map)

Custom tags for categorizing the email. Accepts a flexible object (map), allowing you to define any key-value pairs.

Maximum key length is 128 characters, and maximum value length is 768 characters.


headers object (map)

Custom email headers (e.g., X-Custom-Header). Accepts a flexible object (map), allowing you to define any key-value pairs.

Maximum key length is 128 characters, and maximum value length is 768 characters. Supports simple, dynamic variables from template data (e.g., {{ campaign_id }}).


attachments array

When specified, it should contain an array of AttachmentObject.


MessageObject

FieldTypeRequiredDescription
fromobjectrequiredThe sender's email address. Must be an EmailObject.
toarrayrequiredCan be a single EmailObject or an array of EmailObject.
ccobjectoptionalCan be a single EmailObject or an array of EmailObject.
bccarrayoptionalCan be a single EmailObject or an array of EmailObject.
reply_toobjectoptionalCan be a single EmailObject or an array of EmailObject.
reference_idstringoptionalA unique identifier for tracking the email. Must be a valid 24-character hexadecimal string.
template_dataintegeroptionalAccepts a flexible key-value object (supports nested objects/arrays) mapping keys to template variables. Values may be strings, numbers, booleans, objects, or arrays.

EmailObject

FieldTypeRequiredDescription
addressstringrequiredEmail address
display_namestringoptionalDisplay name for the email.

AttachmentObject

FieldTypeRequiredDescription
file_namestringrequiredName of the file to attach.
content_typestringoptionalMIME type of the file. If not specified, we'll try to guess it, otherwise defaults to application/octet-stream.
contentstringrequiredBase64-encoded content of the file.
inlinebooloptionalIf true, the attachment will be treated as an inline image. Defaults to false. This is useful for embedding images in HTML emails.

Sample Request

The following is a sample request to send an email.

POST https://smtp.maileroo.com/api/v2/emails/template
Content-Type: application/json
{
"subject": "Welcome {{ first_name }} - Your Exclusive Offer Awaits!",
"messages": [
{
"from": {
"address": "[email protected]",
"display_name": "John Doe"
},
"to": [
{
"address": "[email protected]",
"display_name": "Jane Smith"
},
{
"address": "[email protected]"
}
],
"cc": {
"address": "[email protected]",
"display_name": "CC Person"
},
"bcc": [
{
"address": "[email protected]"
},
{
"address": "[email protected]",
"display_name": "Hidden Two"
}
],
"reply_to": {
"address": "[email protected]",
"display_name": "Support Team"
},
"reference_id": "5f2b4c9d8a7e4f3b2c1d9e8f",
"template_data": {
"first_name": "Jane",
"last_name": "Smith",
"discount_code": "WELCOME50",
"account_info": {
"plan": "Enterprise",
"region": "APAC"
},
"features": [
"SMTP Relay",
"Email API",
"Templates"
]
}
},
{
"from": {
"address": "[email protected]",
"display_name": "Offers Team"
},
"to": [
{
"address": "[email protected]",
"display_name": "Bob Johnson"
}
],
"reference_id": "9f1c3b8a4d2e7f3c1a0b9d8e",
"template_data": {
"first_name": "Bob",
"last_name": "Johnson",
"discount_code": "SUMMER25",
"preferences": {
"newsletter": true,
"promotions": false
}
}
}
],
"template_id": 2048,
"plain": "Hi {{ first_name }},\n\nThanks for joining us! Use your code {{ discount_code }} to get started.",
"html": "<h1>Hi {{ first_name }}</h1><p>Thanks for joining us! Use your code <strong>{{ discount_code }}</strong> to get started.</p>",
"tracking": true,
"tags": {
"campaign": "welcome-series",
"region": "APAC",
"batch": "batch-1"
},
"headers": {
"X-Campaign-ID": "{{ campaign }}",
"X-Custom-Header": "CustomValue"
},
"attachments": [
{
"file_name": "brochure.pdf",
"content_type": "application/pdf",
"content": "JVBERi0xLjUKJYGBgYEKC... (truncated base64)",
"inline": false
},
{
"file_name": "logo.png",
"content_type": "image/png",
"content": "iVBORw0KGgoAAAANSUhEUgAA... (truncated base64)",
"inline": true
}
]
}

Sample Response

{
"success": true,
"message": "The email has been scheduled for delivery.",
"data": {
"reference_ids": [
"8d6bda8b298ac128125d9d30",
"16ade7e1d359adc9c0bb1315"
]
}
}