API Reference
Send an email
Queue a single email for delivery. Authenticate with an API key as a Bearer token. On success the message id is returned; the message is delivered asynchronously. Every request must send a non-browser User-Agent.
POST
/
emails
curl --request POST \
--url https://api.mailkube.com/mta/v1/emails \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"from": "Acme <[email protected]>",
"to": "[email protected]",
"subject": "Welcome to Acme",
"html": "<h1>Welcome</h1><p>Thanks for signing up.</p>"
}
'{
"id": "8f1d2c3b-4a5e-6f70-8910-a1b2c3d4e5f6",
"message_id": "<[email protected]>"
}{
"id": "b2c3d4e5-6f70-4a1b-8c2d-3e4f5a6b7c8d",
"message_id": "<[email protected]>",
"object": "scheduled_email",
"status": "scheduled",
"scheduled_at": "2026-08-20T07:00:00Z",
"batch_id": "campaign-x"
}{
"name": "missing_user_agent",
"message": "A User-Agent header is required.",
"statusCode": 400
}{
"name": "invalid_api_key",
"message": "API key is invalid.",
"statusCode": 403
}{
"name": "template_not_found",
"message": "Template not found.",
"statusCode": 404
}{
"name": "validation_error",
"message": "<string>",
"statusCode": 123
}{
"name": "validation_error",
"message": "<string>",
"statusCode": 123
}{
"name": "invalid_idempotent_request",
"message": "This Idempotency-Key was already used with a different payload.",
"statusCode": 409
}{
"name": "validation_error",
"message": "<string>",
"statusCode": 123
}{
"name": "validation_error",
"message": "The `to` field contains an invalid email address.",
"statusCode": 422
}{
"name": "rate_limit_exceeded",
"message": "Too many requests. Please slow down.",
"statusCode": 429
}{
"name": "application_error",
"message": "An unexpected error occurred.",
"statusCode": 500
}Authorizations
An API key created in the dashboard, sent as Authorization: Bearer mk_....
Headers
A unique key making this write retry-safe. A repeat request with the same key and a byte-identical body returns the original response instead of executing again (24-hour window). Max 256 characters. See Idempotency.
Maximum string length:
256Body
application/json
A send carries either raw content (html, text, or both) or a saved template via template_id. template_id is mutually exclusive with html and text.
Sender address, optionally with a display name. The address domain must be a verified domain on your account.
Example:
"Acme <[email protected]>"
Primary recipients. A request accepts at most 50 to addresses; the combined plan cap on to, cc, and bcc also applies.
Maximum array length:
50Subject line (max 255 characters). Single-line: a carriage return or line feed is rejected.
Maximum string length:
255Pattern:
^[^\r\n]*$HTML body. Optional, but a raw-content send needs html and/or text. Omit when using template_id.
Plain-text body. Optional; for an html-only send the text part is derived from html. A text-only send is valid. Omit when using template_id.
Carbon-copy recipients.
Blind-carbon-copy recipients.
Reply-to address or addresses. Sets the message's Reply-To header only: these are not delivery recipients and are not counted against recipient caps.
Custom message headers, up to 20. Names may contain only ASCII letters, digits and hyphens, max 64 characters. Values are single-line (no CR/LF), max 998 characters. Structural headers the platform owns are ignored if supplied: From, To, Cc, Bcc, Subject, Reply-To, MIME-Version, Content-Type, Content-Transfer-Encoding, Date, Message-ID.
Show child attributes
Show child attributes
Files attached to the send.
Show child attributes
Show child attributes
Optional free-form labels for your own filtering and reporting. Up to 20 tags, each a { name, value } pair. Tag names must be unique within the send. Values are excluded from aggregate metrics and are not encrypted, so never put personal data in a tag.
Maximum array length:
20Show child attributes
Show child attributes
Schedule the send for a future instant. Full ISO-8601 with a timezone offset; any offset is accepted and the value is normalized to UTC. A naive, offset-less value is rejected. Must be strictly in the future, and no more than 30 days ahead. The response is then 202 with a scheduled_email object rather than 200. Requires the scheduling plan entitlement. See Scheduled emails.
Example:
"2026-08-20T09:00:00+02:00"
Optional grouping label for a scheduled send, so a whole campaign can be canceled or rescheduled in one call. Valid only together with scheduled_at. Supplying it on an immediate send returns a validation_error.
Maximum string length:
64Example:
"campaign-x"
Send from a saved template instead of raw content. The body (HTML and a derived text part) is rendered server-side. Mutually exclusive with html and text.
Template version: a positive version number or "latest". Defaults to "latest". Only used with template_id.
Values for the template's {{variable_id}} placeholders. Unknown variables are ignored; variables marked required must be supplied. The JSON encoding of this object is capped at 16 KB on every plan, and exceeding it returns template_variables_too_large. Only used with template_id.
Show child attributes
Show child attributes
Optional mailing-list topic slug this send is attributed to. 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 quota is charged. Resolved to the sending domain's apex.
Maximum string length:
16Response
The email was accepted for delivery.
The acknowledgment for an immediate send.
Unique identifier for the accepted message.
The RFC 5322 Message-ID assigned to the message, in <uuid@host> form. Thread replies by echoing it in the In-Reply-To and References headers of a later send. Platform-assigned; a caller-supplied Message-ID header is ignored.
Example:
curl --request POST \
--url https://api.mailkube.com/mta/v1/emails \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"from": "Acme <[email protected]>",
"to": "[email protected]",
"subject": "Welcome to Acme",
"html": "<h1>Welcome</h1><p>Thanks for signing up.</p>"
}
'{
"id": "8f1d2c3b-4a5e-6f70-8910-a1b2c3d4e5f6",
"message_id": "<[email protected]>"
}{
"id": "b2c3d4e5-6f70-4a1b-8c2d-3e4f5a6b7c8d",
"message_id": "<[email protected]>",
"object": "scheduled_email",
"status": "scheduled",
"scheduled_at": "2026-08-20T07:00:00Z",
"batch_id": "campaign-x"
}{
"name": "missing_user_agent",
"message": "A User-Agent header is required.",
"statusCode": 400
}{
"name": "invalid_api_key",
"message": "API key is invalid.",
"statusCode": 403
}{
"name": "template_not_found",
"message": "Template not found.",
"statusCode": 404
}{
"name": "validation_error",
"message": "<string>",
"statusCode": 123
}{
"name": "validation_error",
"message": "<string>",
"statusCode": 123
}{
"name": "invalid_idempotent_request",
"message": "This Idempotency-Key was already used with a different payload.",
"statusCode": 409
}{
"name": "validation_error",
"message": "<string>",
"statusCode": 123
}{
"name": "validation_error",
"message": "The `to` field contains an invalid email address.",
"statusCode": 422
}{
"name": "rate_limit_exceeded",
"message": "Too many requests. Please slow down.",
"statusCode": 429
}{
"name": "application_error",
"message": "An unexpected error occurred.",
"statusCode": 500
}