Command reference

Every flag on this page is also in mailkube help <command>. This is the searchable copy.

Global flags

These work on any command.

Flag	Type	Default	Description
`--api-key`	string		API key, overriding the stored one
`--base-url`	string	`https://api.mailkube.com/mta/v1/`	API base URL, overriding the default
`--config`	path	platform config dir	path to the config file
`--jq`	string		project the output through a jq expression
`--no-color`	bool	`false`	never write ANSI colour
`-o`, `--output`	string	inferred	output format: `text`, `json`, `ndjson` or `yaml`
`--profile`	string	`default`	profile to use
`-q`, `--quiet`	bool	`false`	suppress progress and hints on stderr
`--timeout`	duration	`30s`	timeout for a single API call
`-v`, `--verbose`	count	`0`	verbose output; repeat for SDK request logging
`-y`, `--yes`	bool	`false`	answer every confirmation with yes

Left alone, --output is inferred from the destination: human text on a terminal, JSON anywhere else. See Scripting.

Send

`emails send`

Send an email over the API, or over SMTP with --transport smtp. Message

Flag	Type	Description
`--from`	string	sender address, optionally with a display name
`--to`	list	recipient address (repeatable)
`--cc`	list	carbon-copy recipient (repeatable)
`--bcc`	list	blind carbon-copy recipient (repeatable)
`--reply-to`	list	Reply-To address (repeatable)
`--subject`	string	subject line
`--text`	string	plain-text body, or `@file`, or `@-` for stdin
`--html`	string	HTML body, or `@file`, or `@-` for stdin
`--header`	list	custom header, as `Name: value` (repeatable)
`--attach`	list	path to a file to attach (repeatable)
`--attach-type`	list	override an attachment’s type, as `filename=mime` (repeatable)
`--tag`	list	message tag, as `name=value` (repeatable)
`--topic`	string	mailing-list topic slug

Templates

Flag	Type	Description
`--template-id`	string	saved template to render instead of a body
`--template-version`	string	template version, or `latest`
`--var`	list	template variable, as `key=value` (repeatable)
`--vars`	string	template variables as a JSON object: `@file` or `@-`

Delivery

Flag	Type	Default	Description
`--transport`	string	`api`	how to send: `api` or `smtp`
`--at`	string		schedule the send: RFC 3339 with an offset, or `+2h`
`--batch-id`	string		group this scheduled send under a batch label
`--idempotency-key`	string		make a retry safe; `auto` derives one from the message
`--smtp-host`	string		submission host
`--smtp-port`	string	`587`	submission port
`--smtp-user`	string		SMTP username, as `localpart@verified-domain`
`--smtp-tls`	string	`starttls`	encryption: `starttls`, the only mode

--at, --batch-id and --idempotency-key are API transport only. Combining one with --transport smtp exits 2. Composing and rehearsing

Flag	Type	Description
`--dry-run`	bool	print the request that would be sent, and send nothing
`--json`	string	full payload as JSON: `@file` or `@-`
`--generate-skeleton`	bool	emit an annotated blank payload and exit
`--sample`	bool	generate a body with links and images
`--link`	list	link to include in the generated body (repeatable)
`--image`	list	image to include in the generated body (repeatable)

scheduled is an alias for scheduled-emails, and reschedule for update, so mailkube scheduled reschedule <id> works.

`scheduled-emails list`

Flag	Type	Default	Description
`--status`	list		filter by status: `scheduled`, `canceled`, `failed` (repeatable)
`--batch-id`	string		filter to one batch label
`--after`	string		only sends due at or after this time
`--before`	string		only sends due at or before this time
`--page`	int		fetch one page by number
`--all`	bool	`false`	walk every page
`--max-items`	int		stop after this many items (client-side)

--page and --all cannot be combined.

`scheduled-emails get <id>`

Show one scheduled send. No flags of its own.

`scheduled-emails update <id>`

Flag	Type	Description
`--at`	string	the new due time: RFC 3339 with an offset, or `+2h`
`--batch-id`	string	move it into this batch at the same time

`scheduled-emails cancel <id>`

Cancel one scheduled send. Prompts unless -y.

`scheduled-emails batches update <batch-id>`

Flag	Type	Description
`--at`	string	the new due time for every email in the batch

`scheduled-emails batches cancel <batch-id>`

Cancel every pending send in a batch. Prompts unless -y.

Develop

`webhooks listen`

Receive webhook events on this machine. Where it listens

Flag	Type	Default	Description
`--host`	string	`127.0.0.1`	address to bind
`--port`	int	`4318`	port to bind
`--path`	string	`/`	path deliveries arrive on
`--public-url`	string		the tunnel URL this listener is reachable at
`--local`	bool	`false`	run without a public URL; only what you post yourself arrives
`--max-body`	string	`1MiB`	largest delivery body accepted

What it shows and keeps

Flag	Type	Default	Description
`--print`	string	`pretty`	human rendering: `pretty`, `raw` or `summary`
`--filter`	list		only handle these event types
`--max-field`	int	`512`	widest rendered field before it is shortened
`--record`	path		append every accepted delivery to this `.jsonl` file

Forwarding

Flag	Type	Default	Description
`--forward`	string		re-post every accepted delivery to this local URL
`--forward-sync`	bool	`false`	wait for the forward before acknowledging the delivery
`--forward-duplicates`	bool	`false`	forward redeliveries as well as new events
`--forward-timeout`	duration	`10s`	how long a forward may take
`--force`	bool	`false`	allow a forward target that is not on this machine

Verification and stopping

Flag	Type	Default	Description
`--secret`	string		endpoint signing secret; `MAILKUBE_WEBHOOK_SECRET` is read too
`--tolerance`	duration	`5m`	accepted clock skew on a delivery timestamp
`--skip-verify`	bool	`false`	accept unverified deliveries (development only)
`--exit-after`	int		stop once this many matching events have arrived
`--exit-timeout`	duration		stop with exit 124 if that has not happened in time

`webhooks simulate`

Flag	Type	Description
`--url`	string	endpoint to post to; loopback unless `--force`
`--event`	string	event type to send; run without it to see the list
`--file`	string	payload to send instead of the sample one (`@file` or `@-`)
`--secret`	string	sign with this secret; `MAILKUBE_WEBHOOK_SECRET` is read too
`--force`	bool	allow a target that is not on this machine

`webhooks verify`

Flag	Type	Default	Description
`--body`	string		the raw payload, as `@file` or `@-` (never re-encoded)
`--id`	string		the `X-Webhook-Id` value
`--ts`	string		the `X-Webhook-Ts` value
`--sig`	string		the `X-Webhook-Sig` value
`--secret`	string		the endpoint signing secret
`--tolerance`	duration	`5m`	accepted age; `0` checks the signature only

`smtp test`

Flag	Type	Default	Description
`--host`	string		submission host
`--port`	string	`587`	submission port
`--user`	string		SMTP username, as `localpart@verified-domain`
`--tls`	string	`starttls`	encryption: `starttls`, the only mode
`--auth`	bool	`false`	also sign in, testing the credential

Set up

`init`

Guided first-time setup. --no-verify stores the credential without checking it.

Flag	Type	Description
`--key`	string	the API key to store; prompted for when omitted
`--smtp`	bool	store SMTP credentials instead of an API key
`--user`	string	the SMTP username, `localpart@verified-domain`
`--no-verify`	bool	store the credential without checking it

`auth logout`

--smtp removes the SMTP credential instead of the API key.

`auth status`

Show which credentials are configured, without contacting anything.

`config`

Command	Purpose
`config get <setting>`	print one setting’s value
`config set <setting> <value>`	store a setting in the config file
`config unset <setting>`	remove a setting from the config file
`config list`	show every setting, its value and where it came from
`config path`	print the path to the config file
`config profile list`	list the stored profiles
`config profile use <profile>`	make a profile the one commands use by default
`config profile delete <profile>`	delete a profile and the credentials in it

Settable keys are api_key, base_url, smtp_user, smtp_host, smtp_port and smtp_tls. See Configuration.

`doctor`

Flag	Type	Description
`--offline`	bool	skip the checks that need a network
`--strict`	bool	treat warnings as failures, for a clean-environment gate

`errors explain [name|code]`

Explain an error name or an SMTP code. --list lists every name and code it explains.

`skill`

Command	Flags
`skill install`	`--dir` where to write, defaults to `.claude/skills`; `--force` overwrite files that differ
`skill path`	`--dir` the directory to resolve instead of the default
`skill show [reference]`	none

`dashboard`

Show what is managed in the dashboard, and where.

`topic [name]`

Read a long-form help topic. Run it bare to list them: exit-codes, files, idempotency, output, pagination, profiles, testing, webhooks.

`version`

Show the CLI and SDK versions. --json is a natural spelling of -o json.

`completion <bash|zsh|fish|powershell>`

Write a shell completion script to stdout. See Install.

Verbs that route you to the dashboard

Account configuration lives in the web app. Typing domains, api-keys, templates, suppressions, contacts, segments, audience, or a webhooks management verb such as create or list, prints the page that owns it and exits 2. mailkube dashboard lists every page with its link. To observe what happened to a message, run webhooks listen. Delivery outcomes arrive as events, and the dashboard’s log view holds the longer history.

Get started

Guides

Reference

Command reference

Global flags

Send

`emails send`

`scheduled-emails list`

`scheduled-emails get <id>`

`scheduled-emails update <id>`

`scheduled-emails cancel <id>`

`scheduled-emails batches update <batch-id>`

`scheduled-emails batches cancel <batch-id>`

Develop

`webhooks listen`

`webhooks simulate`

`webhooks verify`

`smtp test`

Set up

`init`

`auth logout`

`auth status`

`config`

`doctor`

`errors explain [name|code]`

`skill`

`dashboard`

`topic [name]`

`version`

`completion <bash|zsh|fish|powershell>`

Verbs that route you to the dashboard

​Global flags

​Send

​emails send

​scheduled-emails list

​scheduled-emails get <id>

​scheduled-emails update <id>

​scheduled-emails cancel <id>

​scheduled-emails batches update <batch-id>

​scheduled-emails batches cancel <batch-id>

​Develop

​webhooks listen

​webhooks simulate

​webhooks verify

​smtp test

​Set up

​init

​auth login

​auth logout

​auth status

​config

​doctor

​errors explain [name|code]

​skill

​dashboard

​topic [name]

​version

​completion <bash|zsh|fish|powershell>

​Verbs that route you to the dashboard

Global flags

Send

`emails send`

`scheduled-emails list`

`scheduled-emails get <id>`

`scheduled-emails update <id>`

`scheduled-emails cancel <id>`

`scheduled-emails batches update <batch-id>`

`scheduled-emails batches cancel <batch-id>`

Develop

`webhooks listen`

`webhooks simulate`

`webhooks verify`

`smtp test`

Set up

`init`

`auth login`

`auth logout`

`auth status`

`config`

`doctor`

`errors explain [name|code]`

`skill`

`dashboard`

`topic [name]`

`version`

`completion <bash|zsh|fish|powershell>`

Verbs that route you to the dashboard