Skip to main content
The CLI writes human output when stdout is a terminal and JSON when it is not. Piping, redirecting or running in CI therefore needs no flag at all, and a command you worked out at a prompt behaves correctly the moment you put it in a script.

​
Forcing a format

-o text is the one worth remembering, for when you want the readable rendering in a file. yml is accepted as a spelling of yaml.

​
The stream split

stdout carries the success payload and nothing else. Progress, warnings, prompts, hints and error reports all go to stderr, and on failure stdout stays empty. That is what makes
safe to write: a command that failed wrote nothing to parse, so the parser never sees half a document. mailkube doctor is the single exception. It writes its whole report to stdout even when it exits non-zero. See Exit codes for why.

​
Projecting with --jq

--jq runs an expression over the output before it is written, using an embedded implementation. It behaves the same on a machine with no jq installed:
A string result is written raw rather than quoted, and captures straight into a variable with no unwrapping:

​
Branching on the result

Exit codes are part of the public contract and stable within a major version, so case $? is safe to write against:
Nothing in the CLI retries by itself. When the server asks for a wait, that is reported and the decision is left to whatever is running the command. See Errors and exit codes for the full table.

​
Non-interactive behavior

Destructive commands prompt and default to no. -y answers yes, which is what a script needs:
-q suppresses progress and hints on stderr. It does not imply -y, and it never suppresses the payload or an error report. A quiet run that fails still tells you why. Prompting also switches itself off where nobody can answer. When stdin is not a terminal, when CI, GITHUB_ACTIONS or MAILKUBE_NO_PROMPT is set to anything non-empty, or when TERM is dumb, the CLI never prompts. A question it cannot ask becomes a usage error, exit 2, telling you to pass -y. Assuming yes would cancel a batch nobody approved. Assuming no would report an operation as refused that was never attempted. --timeout bounds a single API call, 30 seconds by default. Exceeding it exits 124, which is a different question from exit 9: 124 means the time you allowed ran out, 9 means the server was never reached.

​
Credentials in CI

Everything can come from the environment, and a CI job needs no config file:
The full list of variables is on the Configuration page. Flags beat environment variables, which beat the config file, and mailkube config list shows which of the three supplied each effective value.

​
Color

Color follows the terminal and the two conventions every tool honors: NO_COLOR turns it off, CLICOLOR_FORCE turns it on. --no-color does the same as the former for a single invocation. MAILKUBE_ASCII=1 swaps the badge glyphs for ASCII ones on a terminal that cannot draw them.

​
A worked example

Send a message, wait for the platform to say what happened to it, and fail the job if it never does:
The listener exits 0 when the event arrives and 124 when it does not, so set -e fails the job on a message that was accepted and never delivered.