Hello, this is an HTML email.
", "recipients": { "to": [ { "name": "Recipient One", "email": "recipient1@example.com" }, { "name": "Recipient Two", "email": "recipient2@example.com" } ], "cc": [ "cc1@example.com", "cc2@example.com" ], "bcc": [ "bcc1@example.com" ] }, "attachments": [ { "name": "file1.pdf", "url": "https://example.com/file1.pdf" }, { "name": "image.png", "url": "https://example.com/image.png" } ] }, "metadata": { "campaignType": "transactional", "timestamp": "2025-08-25T10:00:00Z", "custom": { "inbox_tracking": "true", "campaign_id": "example-campaign-id" } }, "version": "1.0" } }, "example-amp-html": { "value": { "email": { "from": "from@example.com", "fromName": "Jane Smith", "replyTo": [ "support@example.com" ], "subject": "AMP Email Example", "text": "This is the plain text version of the email.", "html": "This is the fallback HTML content.
", "amp_html": "Hello AMP world!
", "recipients": { "to": [ { "name": "Recipient AMP", "email": "recipient-amp@example.com" } ], "cc": [ "cc-amp@example.com" ], "bcc": [ "bcc-amp@example.com" ] }, "attachments": [ { "name": "manual.pdf", "url": "https://example.com/manual.pdf" } ] }, "metadata": { "campaignType": "marketing", "timestamp": "2025-08-25T11:30:00Z", "custom": { "campaign_id": "CAMP-123", "inbox_tracking": "true" } }, "version": "2.0" } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } }, "examples": { "success": { "value": { "status": "SUCCESS", "statusCode": 1000, "message": "NA" } } } } } }, "400": { "description": "Payload Not Acceptable", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" }, "supportedVersion": { "type": "string" } } }, "examples": { "unsupported-version": { "value": { "status": "ERROR", "statusCode": 9022, "message": "Unsupported version", "supportedVersion": "1.0 or 2.0" } } } } } } } } }, "/email-api": { "post": { "summary": "Send Personalized Email", "operationId": "send-personalized-email-mail-merge", "description": "Send transactional or marketing emails with **per-recipient personalization** (mail merge). Same request structure as `POST /email`, plus an optional `merge_vars` object on each `recipients.to[]` entry.\n\n**Personalization:**\n- `{{variable}}` placeholders in `subject`, `text`, `html`, `amp_html` and `fromName` are replaced with that recipient's `merge_vars` values.\n- In `html`, `{{var}}` is HTML-escaped; use `{{{var}}}` (triple brace) to inject raw HTML (pre-trusted content only).\n- Dot-notation walks nested objects: `{{order.id}}`, `{{order.shipping.city}}`.\n- A missing key renders as an empty string (never blocks the send).\n- Rendering activates only when at least one recipient carries a non-empty `merge_vars`; otherwise `{{...}}` is delivered literally (identical to `/email`).\n\n**CC / BCC:** cc and bcc recipients receive an audit copy rendered against the **first** `to` recipient's `merge_vars` scope.\n\n**Notes:**\n- `merge_vars` must be a JSON object \u2014 a non-object value returns `400`.\n- The combined size of all recipients' `merge_vars` must be \u2264 100 KB, else `413`.\n- `replyTo` must be a verified sender address; it does **not** support `{{var}}` templates.\n- Mail merge is supported only on this HTTP endpoint (not on SMTP relay).", "tags": [ "Email" ], "servers": [ { "url": "https://email-api.mailercloud.com" } ], "parameters": [ { "name": "Content-Type", "in": "header", "required": true, "description": "Request body type", "schema": { "type": "string", "default": "application/json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "version" ], "properties": { "email": { "type": "object", "required": [ "from", "subject", "recipients" ], "properties": { "from": { "type": "string", "description": "Sender email address. Must belong to a verified sender on your Mailercloud account." }, "fromName": { "type": "string", "description": "Sender display name shown in the recipient\u2019s inbox. Supports `{{var}}` substitution." }, "replyTo": { "type": "array", "items": { "type": "string" }, "description": "Address(es) replies are sent to. Must be a verified sender address; does **not** support `{{var}}` templates." }, "subject": { "type": "string", "description": "Email subject line. Supports `{{var}}` substitution." }, "text": { "type": "string", "description": "Plain-text version of the message. Supports `{{var}}` substitution. Recommended alongside `html` for deliverability." }, "amp_html": { "type": "string", "description": "AMP for Email body. Requires `version: \"2.0\"`. Supports `{{var}}` substitution (not HTML-escaped)." }, "html": { "type": "string", "description": "HTML body. Supports `{{var}}` (HTML-escaped) and `{{{var}}}` (raw, unescaped \u2014 pre-trusted content only)." }, "recipients": { "type": "object", "properties": { "to": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Recipient display name." }, "email": { "type": "string", "description": "Recipient email address." }, "merge_vars": { "type": "object", "additionalProperties": true, "description": "Per-recipient personalization values, referenced as `{{key}}` in the subject and body. Nested objects are addressed with dot notation (`{{order.id}}`). Must be a JSON object; combined size across all recipients \u2264 100 KB.", "examples": [ { "first_name": "Alice", "order": { "city": "Berlin" } } ] } } }, "description": "Primary recipients. Each entry may carry its own `merge_vars` object for per-recipient personalization." }, "cc": { "type": "array", "items": { "type": "string" }, "description": "Email addresses to receive a carbon copy, as plain strings. CC copies are rendered against the first `to` recipient\u2019s `merge_vars`." }, "bcc": { "type": "array", "items": { "type": "string" }, "description": "Email addresses to receive a blind carbon copy, as plain strings. Rendered like CC against the first `to` recipient\u2019s scope." } }, "description": "Recipients of this message." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "File name shown to the recipient, including the extension." }, "url": { "type": "string", "description": "Publicly accessible URL the file is fetched from at send time." } } }, "description": "Files to attach to the message." } }, "description": "The message payload." }, "metadata": { "type": "object", "properties": { "campaignType": { "type": "string", "description": "Campaign type accepts only two values: \"TRANSACTIONAL\" or \"PROMOTIONAL\"." }, "timestamp": { "type": "string" }, "custom": { "type": "object", "properties": { "inbox_tracking": { "type": "string" }, "campaign_id": { "type": "string" } }, "description": "Custom key\u2013value metadata. The reserved keys `inbox_tracking` and `campaign_id` connect a send to inbox-placement tracking \u2014 see [List Email API Inbox-Tracking Campaigns](/api-reference/email/list-inbox-tracking-campaigns)." } }, "description": "Optional metadata recorded with the message." }, "version": { "type": "string", "enum": [ "1.0", "2.0" ], "description": "Use `1.0` when only `html` is sent. Use `2.0` when `amp_html` is included." } } }, "examples": { "example-merge-vars": { "value": { "email": { "from": "from@example.com", "fromName": "John Doe", "replyTo": [ "from@example.com" ], "subject": "Hi {{first_name}}, your order {{order.id}} shipped", "text": "Hi {{first_name}}, order {{order.id}} ships to {{order.city}}.", "html": "Hi {{first_name}} from {{company}},
Order {{order.id}} ships to {{order.city}}.
", "recipients": { "to": [ { "name": "Recipient One", "email": "recipient1@example.com", "merge_vars": { "first_name": "Alice", "company": "Acme", "order": { "id": "A-100", "city": "Berlin" } } }, { "name": "Recipient Two", "email": "recipient2@example.com", "merge_vars": { "first_name": "Bob", "company": "Acme", "order": { "id": "A-101", "city": "Paris" } } } ], "cc": [ "cc1@example.com" ], "bcc": [ "bcc1@example.com" ] } }, "metadata": { "campaignType": "TRANSACTIONAL", "timestamp": "2026-04-15T10:00:00Z", "custom": { "inbox_tracking": "false", "campaign_id": "" } }, "version": "1.0" }, "summary": "Per-recipient merge vars" }, "example-raw-html-and-dot-notation": { "value": { "email": { "from": "from@example.com", "fromName": "Jane Smith", "subject": "{{first_name}}, your {{plan.name}} is ready", "html": "Hi {{first_name}},
Plan: {{plan.name}} ({{plan.price}})
", "recipients": { "to": [ { "name": "Recipient AMP", "email": "recipient-amp@example.com", "merge_vars": { "first_name": "Carol", "banner_html": "View", "plan": { "name": "Pro", "price": "$49" } } } ] } }, "metadata": { "campaignType": "PROMOTIONAL", "custom": { "inbox_tracking": "true", "campaign_id": "CAMP-123" } }, "version": "1.0" }, "summary": "Raw HTML + dot notation" } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } }, "examples": { "success": { "value": { "status": "SUCCESS", "statusCode": 1000, "message": "NA" } } } } } }, "400": { "description": "Validation error (invalid merge_vars shape, invalid recipient, unsupported version, etc.)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } }, "examples": { "invalid-merge-vars": { "value": { "status": "ERROR", "statusCode": 9999, "message": "merge_vars must be an object" } } } } } }, "413": { "description": "Payload Too Large \u2014 combined merge_vars across all recipients exceeds 100 KB", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } }, "examples": { "merge-vars-too-large": { "value": { "status": "ERROR", "statusCode": 9999, "message": "merge_vars exceeds 100 KB limit" } } } } } } } } }, "/v2/email/inbox-tracking": { "post": { "summary": "List Inbox-Tracking Campaigns", "operationId": "list-email-api-inbox-tracking-campaigns", "description": "API to get inbox tracking details for Email API campaigns. Returns a paginated list of campaigns enriched with inbox / spam / missed placement percentages and a per-mailbox-provider breakdown. Supports filtering by campaign id, subject, sender and date range, plus sorting on key metrics.\n\n**Sample Code**", "tags": [ "Email" ], "servers": [ { "url": "https://cloudapi.mailercloud.com" } ], "parameters": [ { "name": "Content-Type", "in": "header", "required": true, "description": "Request body type", "schema": { "type": "string", "default": "application/json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "page", "limit" ], "properties": { "page": { "type": "integer", "minimum": 1, "description": "1-based page number.", "examples": [ 1 ] }, "limit": { "type": "integer", "enum": [ 10, 20, 50, 100 ], "description": "Records per page. Must be one of 10, 20, 50, 100.", "examples": [ 10 ] }, "campaign_id": { "type": "string", "description": "Filter by campaign id (partial match).", "examples": [ "750373463838949401" ] }, "subject": { "type": "string", "description": "Filter by subject (partial match).", "examples": [ "welcome" ] }, "sender": { "type": "string", "description": "Filter by sender email/name (partial match).", "examples": [ "noreply@yourdomain.com" ] }, "date_from": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Inclusive lower bound (YYYY-MM-DD).", "examples": [ "2026-04-01" ] }, "date_to": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Inclusive upper bound (YYYY-MM-DD).", "examples": [ "2026-04-30" ] }, "sort_field": { "type": "string", "enum": [ "inbox_percentage", "created_date", "campaign_id", "subject", "sent", "opens" ], "description": "Field to sort by.", "examples": [ "created_date" ] }, "sort_order": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction.", "examples": [ "desc" ] } } }, "examples": { "minimal-first-page": { "value": { "page": 1, "limit": 10 } }, "sorted-by-inbox-placement": { "value": { "page": 1, "limit": 20, "sort_field": "inbox_percentage", "sort_order": "desc" } }, "filter-subject-and-date-range": { "value": { "page": 1, "limit": 50, "subject": "welcome", "sender": "noreply@yourdomain.com", "date_from": "2026-04-01", "date_to": "2026-04-30", "sort_field": "created_date", "sort_order": "desc" } }, "lookup-by-campaign-id": { "value": { "page": 1, "limit": 10, "campaign_id": "750373463838949401" } } } } } }, "responses": { "200": { "description": "Campaign list retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "examples": [ true ] }, "message": { "type": "string", "examples": [ "requested campaign list" ] }, "data": { "type": "array", "description": "List of campaigns matching the filter.", "items": { "type": "object", "properties": { "campaign_id": { "type": "string", "description": "MailerCloud campaign identifier (string-encoded big integer)." }, "subject": { "type": "string" }, "sent": { "type": "string", "description": "Total sent count (string-encoded integer)." }, "opens": { "type": "string", "description": "Total open count (string-encoded integer)." }, "created_date": { "type": "string", "description": "Creation timestamp in client's timezone (YYYY-MM-DD HH:mm:ss)." }, "inbox_percentage": { "type": "number", "format": "float", "description": "Percentage of tracked seed deliveries that landed in the inbox.", "minimum": -3.402823669209385e+38, "maximum": 3.402823669209385e+38 }, "spam_percentage": { "type": "number", "format": "float", "description": "Percentage of tracked seed deliveries that landed in spam.", "minimum": -3.402823669209385e+38, "maximum": 3.402823669209385e+38 }, "missed_percentage": { "type": "number", "format": "float", "description": "Percentage of tracked seed deliveries that were missed.", "minimum": -3.402823669209385e+38, "maximum": 3.402823669209385e+38 }, "providers": { "type": "array", "description": "Per-mailbox-provider placement breakdown.", "items": { "type": "object", "properties": { "provider": { "type": "string", "description": "Mailbox provider domain (e.g. gmail.com, yahoo.com)." }, "inbox": { "type": "string", "description": "Inbox placement count (string-encoded integer)." }, "spam": { "type": "string", "description": "Spam placement count (string-encoded integer)." }, "missed": { "type": "string", "description": "Missed placement count (string-encoded integer)." } } } } } } }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer", "examples": [ 1 ] }, "per_page_count": { "type": "integer", "examples": [ 10 ] }, "total_count": { "type": "integer", "examples": [ 137 ] } } } } }, "examples": { "sample-list": { "value": { "status": true, "message": "requested campaign list", "data": [ { "campaign_id": "750373463838949401", "subject": "Welcome to MailerCloud", "sent": "10000", "opens": "4231", "created_date": "2026-04-15 09:30:00", "inbox_percentage": 92.5, "spam_percentage": 5, "missed_percentage": 2.5, "providers": [ { "provider": "gmail.com", "inbox": "85", "spam": "10", "missed": "5" }, { "provider": "yahoo.com", "inbox": "95", "spam": "3", "missed": "2" }, { "provider": "outlook.com", "inbox": "90", "spam": "7", "missed": "3" } ] } ], "pagination": { "current_page": 1, "per_page_count": 10, "total_count": 137 } } } } } } }, "400": { "description": "Validation Error (invalid field, bad date format, missing required fields)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "examples": [ false ] }, "message": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "examples": { "invalid-date": { "value": { "status": false, "message": "requested campaign list", "errors": [ { "field": "date_from", "message": "Date must be in YYYY-MM-DD format" } ] } } } } } }, "401": { "description": "Authorization failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "examples": { "auth-failed": { "value": { "errors": [ { "field": "", "message": "Authorization failed" } ] } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "examples": [ false ] }, "message": { "type": "string" }, "error": { "type": "string", "description": "Free-form error string." } } } } } } } } } }, "tags": [ { "name": "Email" } ] }