Send Templated Email
You can send an email using a template by making a POST request with a JSON payload to the API endpoint. The request should include the sender's and recipient's email addresses, the subject line, the template ID, and the corresponding template data.
Endpoint
POST https://smtp.maileroo.com/api/v2/emails/template
Request Body
from object required
This can be anything @yourdomain.com, but it must be a verified domain in your Maileroo account.
Must be an EmailObject.
to array | object required
Primary recipient(s). Can be a single EmailObject or an array of EmailObject.
cc array | object
Carbon copy recipients. Can be a single EmailObject or an array of EmailObject.
bcc array | object
Blind carbon copy recipients. Can be a single EmailObject or an array of EmailObject.
reply_to array | object
Reply-to email addresses. Can be a single EmailObject or an array of EmailObject.
subject string required
The email subject line, limited to 255 characters. It also supports simple, dynamic variables from template data (for example, {{ first_name }}
).
template_id integer required
The ID of the template to use for the email. Found in the "Templates" page of your Maileroo dashboard.
template_data object
Accepts a flexible key-value object (supports nesting of objects and arrays) where each key maps to a variable in the template. The values can be strings, numbers, booleans, objects, or arrays.
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.
scheduled_at string
If you want to schedule the email for future delivery, specify the time in ISO 8601 format (e.g., 2024-08-05T11:52:01.858Z
). You can also use natural language like tomorrow at 2pm
, in 2 hours
, etc. relative to the server time.
reference_id string
Unique 24-char hex ID for tracking. Auto-generated if omitted. Refer to Reference ID for more details.
EmailObject
Field | Type | Required | Description |
---|---|---|---|
address | string | required | Email address |
display_name | string | optional | Display name for the email. |
AttachmentObject
Field | Type | Required | Description |
---|---|---|---|
file_name | string | required | Name of the file to attach. |
content_type | string | optional | MIME type of the file. If not specified, we'll try to guess it, otherwise defaults to application/octet-stream . |
content | string | required | Base64-encoded content of the file. |
inline | bool | optional | If 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
{
"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"
},
"subject": "Welcome to Maileroo: Your Complete Email Delivery Solution",
"template_id": 1024,
"template_data": {
"first_name": "Jane",
"last_name": "Smith",
"account_info": {
"plan": "Enterprise",
"region": "APAC"
},
"features": [
"SMTP Relay",
"Email API",
"Email Templates"
],
"welcome_bonus": true
},
"tracking": true,
"tags": {
"campaign": "welcome-series",
"user_id": "12345",
"source": "landing-page"
},
"headers": {
"X-Custom-Header": "CustomValue",
"X-Trace-ID": "trace-abc123xyz"
},
"attachments": [
{
"file_name": "document.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
}
],
"scheduled_at": "2025-08-01T15:30:00Z",
"reference_id": "5f2b4c9d8a7e4f3b2c1d9e8f"
}
Sample Response
{
"success": true,
"message": "The email has been scheduled for delivery.",
"data": {
"reference_id": "c843204e3af03193bd14f339"
}
}