Skip to main content
A profile holds two credentials, and they are separate principals:
  • an API key for the REST transport, a string that starts with mk_
  • an SMTP username and password for submission, where the username is localpart@verified-domain
Either may be absent. Neither substitutes for the other, so asking for --transport smtp with no SMTP credential is an error rather than a quiet fallback to REST. Both are created in the dashboard under Credentials, against a verified domain.

​
First-time setup

It asks for an API key, verifies it against the API, tells you whether it worked, and then offers to add SMTP credentials as well. Say no to that if you only plan to send over REST; you can add them later. Pass --no-verify to store a key without checking it, which is occasionally useful on a machine with no route to the API yet.

​
Storing credentials directly

Both prompt for the secret rather than taking it on the command line. --key exists for scripted setup, at the cost of putting the key in your shell history. To check what is configured, without contacting anything:
Removing a credential is the mirror image: mailkube auth logout drops the API key, and mailkube auth logout --smtp drops the SMTP one.

​
Where credentials live

In a TOML file in your platform’s own configuration directory, created readable only by you: mailkube config path prints the real one. See Configuration for the file format and the full precedence rules.
smtp_password cannot be passed to mailkube config set. An argument is visible in your shell history and in the process list, so the command refuses it and points you at mailkube auth login --smtp or the MAILKUBE_SMTP_PASSWORD environment variable.

​
Without storing anything

Every credential can come from the environment instead, which is what you want in CI:
Or per invocation, with --api-key. Flags beat environment variables, which beat the config file.

​
More than one sending domain

An SMTP credential is bound to a single domain, and a profile holds one SMTP credential. Two sending domains therefore means two profiles:
--profile overrides the active profile for one command. MAILKUBE_PROFILE does the same for a shell session.

​
When a key is rejected

A rejected credential exits 3, and that code is never worth retrying: a key the server refused will not be accepted a moment later, and hammering it is how an address gets blocked. A malformed key and an unknown key are deliberately indistinguishable, so “the key looks wrong” and “the key is not registered” produce the same answer. If the credential is fine but something else in the environment is not, mailkube doctor checks the whole picture.

​
Next steps

Quickstart

Send your first message.

Configuration

Profiles, settings, precedence, and every environment variable.