Skip to main content
The Quickstart sends a minimal message. This page covers the rest of the send request. The full field list is in the API reference. The fragments below are the wire fields. Every SDK takes the same names under its own conventions, so a field documented here reaches the same place through a typed client:
Where a field behaves differently over SMTP, the section says so. The CLI accepts the same payload through --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, send html, text, or both; at least one is required:
  • html + text. Full control over both parts.
  • html only. A plain-text part is derived from your HTML automatically.
  • text only. A plain-text message.
Text alone is accepted:

Send with a template

A saved template can replace raw content. Reference it with template_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_id is the template’s UUID (required for a template send).
  • template_version is a positive version number or "latest" (the default).
  • variables holds values for the template’s {{variable_id}} placeholders. Unknown variables are ignored; any variable marked required must be supplied, or the send fails with missing_required_variable. An unknown template or version fails with template_not_found.
Attachments and custom headers work with a template just as they do with raw content.

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 the topic 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.
An unknown or disabled topic is rejected before your quota is charged, with a 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 the tags 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.
A tag that breaks these rules (a bad character, an oversized field, a missing value key, a duplicate name, or more than 20 tags) is rejected with a validation_error.
Tag values are not encrypted and are excluded from aggregate metrics, so never put personal data (a recipient address, a name, anything identifying) in a tag name or value.

Schedule a send

Add a scheduled_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:
A scheduled send returns 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:
The total message size, including attachments, is capped by your plan (10 to 25 MB depending on tier). Oversized messages are rejected; see Plans & limits.
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 the headers object:
Up to 20 headers per message. A name may contain only ASCII letters, digits and hyphens, up to 64 characters, so 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 add List-Unsubscribe or List-Unsubscribe-Post for you. Neither is a structural header, so set them through headers and they go out on the message:
The URL is yours. Point it at an endpoint you host that records the opt-out. Sending 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 a message_id, the RFC Message-ID mailkube assigned to the message:
To make a later email thread as a reply in the recipient’s inbox, echo that 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-readable name, a message, and the HTTP statusCode:
Branch on name and statusCode in your code. The full list is in Errors, and rate-limit behavior (including Retry-After) is in Rate limits.