Skip to main content
To send a saved template over SMTP, add the X-Mailkube-Template-* headers to your message instead of composing the body yourself. mailkube renders the template (HTML and a derived text part) server-side, then delivers it. The headers are stripped before the message reaches the recipient.

Headers

Variables fill the template’s {{variable_id}} placeholders. Unknown variables are ignored; any variable marked required must be supplied. X-Mailkube-Template-Variables is capped at 16 KB, measured on the JSON, so the keys, quotes, and separators count toward it and non-ASCII characters can count as up to 6 bytes each. A raw header past the cap is refused with 552 X-Mailkube-Template-Variables header too large; a payload that fits the header but whose canonical JSON encoding still exceeds the ceiling is rejected with 550 5.6.0 before the template renders. See Plans & limits for the fixed ceilings.

Example

A submitted message that renders template 3f6c2e1a-… with one variable:
Write those headers to a file and submit it with curl, which uploads the message verbatim and so leaves the JSON header untouched:
The blank line at the end of the file terminates the header block. The body after it is discarded, because the template is rendered server-side and replaces whatever body you submit.
Attachments are preserved. When your message carries attachments, they are kept and the rendered template body is delivered alongside them.
X-Mailkube-Template-Variables must be a valid JSON object; anything else is refused with 550 Invalid X-Mailkube-Template-Variables JSON. A missing required variable or a nonexistent template is rejected with 550 5.6.0 (the reply text names the missing variable), and a template that exists but is still a draft with 550 5.7.0 Template is not published. See Error codes.
The From address must still use the domain your credential is bound to, exactly as for a normal send.