--json.
The from address
from is required and must use a domain you’ve verified. You can include a display name:
Content: HTML, plain text, or a template
A send carries either raw content or a template. For raw content, sendhtml, text, or both; at least one is required:
html+text. Full control over both parts.htmlonly. A plain-text part is derived from your HTML automatically.textonly. A plain-text message.
Send with a template
A saved template can replace raw content. Reference it withtemplate_id, and the body (HTML and a derived text part) is rendered server-side. Sending html or text alongside a template is a validation_error.
template_idis the template’s UUID (required for a template send).template_versionis a positive version number or"latest"(the default).variablesholds values for the template’s{{variable_id}}placeholders. Unknown variables are ignored; any variable marked required must be supplied, or the send fails withmissing_required_variable. An unknown template or version fails withtemplate_not_found.
Recipients
to, cc, and bcc each accept a single address or an array:
The combined number of
to, cc, and bcc recipients on one message is capped by your plan; see Plans & limits. Independently of the plan, to accepts at most 50 addresses in a single request.reply_to takes the same shape: a single address or an array, display names allowed, validated like any other address field. It sets the message’s Reply-To header only; reply-to addresses are not delivery recipients and do not count against recipient caps.
Attribute a send to a topic
Optionally attribute a send to a mailing-list topic with thetopic field (the topic slug, up to 16 characters). An opt-out topic filters recipients who unsubscribed from it; an opt-in topic tags the send without filtering.
topic_not_found or topic_disabled error. See Topics for the full behavior.
Tag your emails
Optionally attach free-form tags to a send with thetags array, a list of { "name": ..., "value": ... } pairs you use for your own filtering and reporting. Each name and value accepts ASCII letters, digits, underscore, and hyphen (^[A-Za-z0-9_-]+$), up to 16 characters for a name and 32 for a value. A name is required and must be unique within the send; the value key must be present too, and may be an empty string. You can attach up to 20 tags per message.
value key, a duplicate name, or more than 20 tags) is rejected with a validation_error.
Schedule a send
Add ascheduled_at timestamp to send the message at a later time. It must be a timezone-aware ISO-8601 instant, strictly in the future and no more than 30 days ahead:
202 with a scheduled_email object; you can then list, reschedule, or cancel it before it goes out. An optional batch_id groups sends so a whole campaign can be canceled or rescheduled at once. Scheduling is a paid plan feature; see Scheduled emails for the full guide.
Times must be absolute ISO-8601 with a timezone offset. Natural-language values like
"in 1 hour" and naive (offset-less) timestamps are rejected.Attachments
Attach files by base64-encoding their content:Attachments are sent inline as base64
content; remote-URL attachments are not supported in v1. Any unrecognized fields in the request body are ignored.Custom headers
Add your own headers with theheaders object:
X-Campaign_Id with its underscore is rejected. A value must be a single line (no carriage return or line feed) of at most 998 characters. Anything else returns validation_error (422).
Headers that describe the message structure are owned by mailkube and ignored if you send them: From, To, Cc, Bcc, Subject, Reply-To, MIME-Version, Content-Type and Content-Transfer-Encoding. Set the addresses and the subject through their own fields instead.
One-click unsubscribe
mailkube does not addList-Unsubscribe or List-Unsubscribe-Post for you. Neither is a structural header, so set them through headers and they go out on the message:
List-Unsubscribe-Post commits you to accepting an HTTP POST at that URL and unsubscribing on the spot, with no confirmation page, which is what RFC 8058 one-click means. On SMTP, add both headers to your message as you would any other.
Major mailbox providers expect bulk senders to offer one-click unsubscribe, so set these on marketing mail. Leave them off transactional mail such as password resets and receipts, which recipients should not be able to switch off.
Topics and these headers do different jobs. A topic filters recipients who have already opted out of it. It does not put an unsubscribe control in the message, because mailbox providers render the control from the header.
Reply threading
Every successful send returns amessage_id, the RFC Message-ID mailkube assigned to the message:
message_id in the In-Reply-To and References headers of the follow-up send:
The
Message-ID is always assigned by mailkube, and Date is set to the time the message is sent. A value you set for either one in headers is ignored. Keep the returned message_id from each send if you plan to thread later messages onto it.Handling errors
Errors use a compact envelope with a machine-readablename, a message, and the HTTP statusCode:
name and statusCode in your code. The full list is in Errors, and rate-limit behavior (including Retry-After) is in Rate limits.