Configuration

Describe your inboxes, aliases, and routing behavior in one config.json file that the CLI manages and the deploy command ships to the Worker.

Why Use This File?

Keeps every destination, alias, and setting in one place so a deploy always ships a complete, consistent picture.
Is validated against a schema before every deploy so typos and missing references never reach your mail.
Is written for you by the CLI so you rarely need to edit JSON by hand.

File Location

The CLI looks for config.json in these locations, in order:

The current working directory.
The project root.
Your platform config directory (for example ~/.config/mailmask/ on Linux).

If none exists, the CLI copies the bundled starter template into the platform config directory. When several files are found, the interactive menu asks which one to use.

warning

The config lists your real inboxes and every alias you own. It is recommended to keep it out of version control; the repository's ignore rules already exclude it.

Example

config.json

json

{
  "destinations": [
    {
      "name": "personal",
      "email": "[email protected]"
    }
  ],
  "aliases": [
    {
      "address": "velvet-harbor-42",
      "destination": "personal",
      "label": "Online shopping",
      "enabled": true
    },
    {
      "address": "trial-signup",
      "destination": "personal",
      "label": "Free trial",
      "enabled": true,
      "expires_at": "2026-12-31T00:00:00.000Z",
      "allowed_senders": [
        "*@example-saas.com"
      ]
    }
  ],
  "settings": {
    "worker_name": "mailmask",
    "base_domain": "mail.example.com",
    "unknown_alias_action": "reject",
    "subaddressing": true,
    "add_alias_headers": true
  }
}

Destinations

Each destination is a real inbox that aliases forward to.

Field	Description
`name`	Short identifier used by aliases. Lowercase letters, numbers, and hyphens only.
`email`	The inbox address. Cloudflare sends it a verification email on the first deploy.

Aliases

Each alias is an address on your base domain.

Field	Description
`address`	The part before the `@`. Lowercase letters, numbers, dots, hyphens, and underscores, up to 64.
`destination`	The `name` of the destination to forward to.
`label`	Optional note about where you used the alias. Added to forwarded mail as `X-Mailmask-Label`.
`enabled`	`false` refuses all mail while keeping the address reserved.
`expires_at`	Optional ISO 8601 timestamp. Mail arriving at or after this time is refused.
`allowed_senders`	Optional list of sender rules. When present, only matching senders get through.
`blocked_senders`	Optional list of sender rules. Matching senders are always refused, even if they are also allowed.

A sender rule is either a full address ([email protected]) or a domain wildcard (*@shop.com). See Sender Rules for how the two lists combine.

Settings

Field	Description
`worker_name`	Name of the Cloudflare Worker. Lowercase letters, numbers, and hyphens.
`base_domain`	The domain (or subdomain) your aliases live on, such as `mail.example.com`.
`unknown_alias_action`	What happens to mail for addresses that are not aliases: `reject`, `drop`, or `forward`.
`default_destination`	Destination that receives unknown-address mail. Required when `unknown_alias_action` is `forward`.
`subaddressing`	When `true`, `alias+tag@` is treated as `alias@`.
`add_alias_headers`	When `true`, forwarded mail carries `X-Mailmask-Alias` and `X-Mailmask-Label` headers.

The interactive Settings menu edits every field.

Notifiers

The optional notifiers list sends a notice whenever a known alias refuses mail. Each entry is an ntfy topic or an ntfy-reverse-proxy context. See Refusal Notifications for the fields.

Validation

mm validate checks the file against the schema and these cross-references:

Every alias points to a destination that exists.
No two destinations share a name, and no two aliases share an address.
default_destination exists whenever it is set.

Deploy runs the same validation and stops if the file is invalid, so nothing broken reaches Cloudflare.

Applying Changes

Alias and setting changes take effect on the next deploy, because the config ships with the Worker. Every CLI command that changes the file reminds you to run mm deploy.