Configuration

Every setting resolves from four places, in this order:

flag  >  environment variable  >  config file  >  built-in default

mailkube config list prints the effective value of every setting together with which of the four supplied it, which is how you answer “why is it using that base URL” without guessing:

{
  "settings": [
    { "setting": "profile",   "value": "default",                            "source": "(default)" },
    { "setting": "api_key",   "value": "mk_a1b2…",                           "source": "env MAILKUBE_API_KEY" },
    { "setting": "base_url",  "value": "https://api.mailkube.com/mta/v1/",   "source": "(default)" },
    { "setting": "smtp_user", "value": "[email protected]",               "source": "config file" },
    { "setting": "smtp_port", "value": "587",                                "source": "(default)" },
    { "setting": "smtp_tls",  "value": "starttls",                           "source": "(default)" },
    { "setting": "timeout",   "value": "30s",                                "source": "(default)" },
    { "setting": "output",    "value": "-",                                  "source": "(not set)" }
  ]
}

An environment variable set to the empty string counts as unset.

Settings

Setting	Default	Set with
`api_key`		`mailkube auth login`
`base_url`	`https://api.mailkube.com/mta/v1/`	`config set`
`smtp_user`		`config set` or `auth login --smtp`
`smtp_host`		`config set`
`smtp_port`	`587`	`config set`
`smtp_tls`	`starttls`	`config set`

smtp_tls accepts starttls, which is the only value: the connection is always encrypted. The trailing slash on base_url is load-bearing. Paths resolve by RFC 3986 reference resolution, where the last segment of the base is replaced rather than appended to, so a base ending /mta/v1 would resolve emails to /mta/emails and return a 404 with nothing to explain it. The CLI appends the slash for you if you set a value without one.

mailkube config set smtp_host smtp.mailkube.com
mailkube config get smtp_host
mailkube config unset smtp_host

api_key is a secret and is never printed in full, by config get or anything else.

smtp_password cannot be set as an argument. An argument is visible in your shell history and in the process list, so the command refuses it. Use mailkube auth login --smtp, or the MAILKUBE_SMTP_PASSWORD environment variable.

Environment variables

Variable	Effect
`MAILKUBE_API_KEY`	the API key
`MAILKUBE_BASE_URL`	the API base URL
`MAILKUBE_PROFILE`	which profile to use
`MAILKUBE_CONFIG`	path to the config file
`MAILKUBE_SMTP_PASSWORD`	the SMTP password
`MAILKUBE_WEBHOOK_SECRET`	endpoint signing secret, read by every `webhooks` command
`MAILKUBE_SKILL_DIR`	where `skill install` writes
`MAILKUBE_ASCII`	set to `1` to replace badge glyphs with ASCII
`NO_COLOR`	turn color off
`CLICOLOR_FORCE`	turn color on
`CI`, `GITHUB_ACTIONS`, `MAILKUBE_NO_PROMPT`	any non-empty value disables prompting; see non-interactive behavior
`TERM`	`dumb` disables prompting and color

--timeout has no environment variable, by design: a timeout is a property of the call you are making rather than of the machine you are on. MAILKUBE_WEBHOOK_SECRET is deliberately never stored in the config file. A signing secret belongs to an endpoint, not to a profile.

Profiles

A profile holds an API key, a base URL, and one SMTP credential. The active one comes from --profile, then MAILKUBE_PROFILE, then active_profile in the file, defaulting to default.

mailkube config profile list
mailkube config profile use staging
mailkube config profile delete staging

Deleting a profile deletes the credentials in it, and asks first unless you pass -y. One SMTP credential per profile is a hard limit, because a credential is bound to one sending domain. More than one sending domain means more than one profile:

mailkube auth login --smtp --user [email protected] --profile marketing
mailkube emails send --profile marketing --transport smtp ...

The config file

TOML, in your platform’s own configuration directory:

Platform	Path
macOS	`~/Library/Application Support/mailkube/config.toml`
Linux	`~/.config/mailkube/config.toml`
Windows	`%AppData%\mailkube\config.toml`

mailkube config path prints the real one. --config and MAILKUBE_CONFIG point somewhere else entirely.

active_profile = "default"

[profiles.default]
api_key  = "mk_..."
base_url = "https://api.mailkube.com/mta/v1/"

[profiles.default.smtp]
username = "[email protected]"
password = "..."
host     = "smtp.mailkube.com"
port     = 587
tls      = "starttls"

The file is created readable only by you, mode 0600 inside a 0700 directory, and every write is atomic and serialized under a lock. It is a plain file rather than an entry in the OS keychain, which is a deliberate trade: it works the same on a server, in a container and on a laptop.

A file that cannot be parsed is never rewritten or repaired. It may hold the only copy of a credential, so the CLI reports the problem and leaves the file exactly as it found it.

Reading values from files

Any flag that could take either literal content or a filename follows one rule:

Value	Meaning
`@path`	read the file at that path
`@-`	read standard input
`\@text`	a literal value that begins with an `@`

It applies to --html, --text, --json, --vars and --body, with at most one @- per invocation. Flags whose value is only ever a path take it bare: --attach, --record, --config.

Get started

Guides

Reference

Settings

Environment variables

Profiles

The config file

Reading values from files

​Settings

​Environment variables

​Profiles

​The config file

​Reading values from files

Settings

Environment variables

Profiles

The config file

Reading values from files