Skip to main content
One command sends mail, and it goes out over the REST API by default:
--transport smtp sends the same message through submission instead. The flags do not change.

Sending safely

There is no sandbox. Every send that is not a --dry-run is real, charged, and attached to your sending reputation, and that includes commands named test and flags named --sample. Four habits keep this cheap:
  • --dry-run first, always. It prints exactly what would be sent, the JSON body on the API transport and the rendered message on SMTP, and sends nothing.
  • Send to an address you control.
  • Prefer a domain that is not your production one. Bounces and complaints attach to the domain that sent them.
  • Know what --sample does. It generates a body containing links and images, which exercises link reputation on whatever domain you send from.
mailkube smtp test submits no message at all, and mailkube doctor sends nothing on either transport. Those two are safe to run as often as you like.

Bodies, files and stdin

Supply --text, --html, or both. Each takes content directly, or reads it from somewhere:
The rule is the same for every flag that could plausibly take either literal content or a filename: It applies to --text, --html, --json, --vars and --body. Only one @- per invocation, since there is only one standard input to consume. Flags whose value is always a path take it bare, with no @: --attach, --record and --config.

Recipients and headers

--to, --cc, --bcc and --reply-to are repeatable, and each also accepts a comma-separated list:
Custom headers go through --header, repeatable, in Name: value form. That is how you thread a reply, using the messageId a previous send returned:

Attachments

--attach takes a path and is repeatable. The type is inferred from the filename, and --attach-type overrides it when the inference is wrong:

Saved templates

A template created in the dashboard can supply the body:
--var is repeatable and takes key=value. For anything with structure, pass the whole set as JSON with --vars, which accepts @file and @-:
--template-version pins a specific version. Leave it off, or pass latest, to render whatever is currently published. A template that exists but has never been published fails with template_not_published, and a variable the template requires but you did not supply fails with missing_required_variable.

Tags and topics

--tag attaches name=value metadata that comes back on webhook events and in the dashboard, and it is repeatable:
--topic names a mailing-list topic slug, and it is what puts a working unsubscribe on a bulk message. See Tags and Topics for the validation rules and what each is for.

Idempotent sends

A send is not idempotent by default. Run it twice and two messages go out, both charged. --idempotency-key makes a repeat safe. The server remembers the key and returns the original response, and the CLI marks it as a replay so a script can tell the two apart:
--idempotency-key auto derives the key from the message itself, which matches how the server binds a key to a body. Re-running an identical command then replays the original response.
Keys are remembered for 24 hours. Under auto, sending the same message twice inside that window replays the first response, and the CLI reports it as a replay. When you mean to send twice, vary the body or pass your own key. Reusing a key with a different body is a conflict rather than a replay, and exits 5.
The response tells you which happened:

Sending later

--at schedules the send for a later time. It takes RFC 3339 with an offset, or a relative shorthand:
The acknowledgment carries "scheduled": true, the due time, and the batch, and it prints the command to cancel it. --batch-id groups sends so a whole campaign can be moved or canceled as a unit. See Scheduled sends.

The SMTP transport

--transport smtp submits the message through the submission server. It uses the SMTP credential stored in your profile, and the per-invocation overrides are --smtp-host, --smtp-port, --smtp-user and --smtp-tls:
The From domain has to match the domain your SMTP credential is bound to. This is a different protocol, not a test mode: it sends for real. SMTP reference covers the wire-level details, and mailkube smtp test checks connectivity and credentials without submitting anything. Three flags belong to the API transport alone: --at, --batch-id and --idempotency-key. Combining any of them with --transport smtp exits 2. Refusing the command is the guarantee that a send you meant to schedule never goes out immediately.

Building the payload by hand

For anything long-lived, keep the message in a file. --generate-skeleton writes an annotated blank payload to get you started:
--json takes the complete request body, from @file or @-, which makes the CLI a thin way to replay whatever your application would have posted. To generate a body with realistic content, --sample produces one containing links and images, and --link and --image add specific ones to it.

Next steps

Scheduled sends

List, reschedule and cancel, one send or a whole batch.

Receiving webhooks

Find out what actually happened to the message.

Errors and exit codes

What each failure means and which ones to retry.

Command reference

Every flag on emails send, in one table.