Send Templated Email

Send an email using a template by making a POST request with a JSON payload to the API endpoint.

POSThttps://smtp.maileroo.com/api/v2/emails/template

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.

Request Body

fromobjectrequired

This can be anything @yourdomain.com, but it must be a verified domain in your Maileroo account. Must be an EmailObject.

toarray | objectrequired

Primary recipient(s). Can be a single EmailObject or an array of EmailObject.

ccarray | objectoptional

Carbon copy recipients. Can be a single EmailObject or an array of EmailObject.

bccarray | objectoptional

Blind carbon copy recipients. Can be a single EmailObject or an array of EmailObject.

reply_toarray | objectoptional

Reply-to email addresses. Can be a single EmailObject or an array of EmailObject.

subjectstringrequired

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

template_idintegerrequired

The ID of the template to use for the email. Found in the "Templates" page of your Maileroo dashboard.

template_dataobjectoptional

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.

trackingbooleanoptional

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

tagsobject (map)optional

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.

headersobject (map)optional

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 }}).

attachmentsarrayoptional

When specified, it should contain an array of AttachmentObject.

scheduled_atstringoptional

If you want to schedule the email for future delivery, specify the time in RFC 3339 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_idstringoptional

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

200 OK

{
  "success": true,
  "message": "The email has been scheduled for delivery.",
  "data": {
    "reference_id": "c843204e3af03193bd14f339"
  }
}

PreviousSend Basic Email Next Send Bulk Emails