Skip to main content

Quick Start

Install the CLI, create your first alias, and deploy the Worker that forwards its mail to your real inbox.

Prerequisites

  • Node.js — v22 or v24, with npm.
  • Cloudflare account — The free plan includes Workers and Cloudflare Email Routing.
  • A domain on Cloudflare — The domain's DNS must be managed by Cloudflare.
  • Email Routing enabled — Turn it on under Email > Email Routing in the Cloudflare dashboard so the mail (MX) records are added.

warning

The deploy command never changes your DNS. If Cloudflare Email Routing is not enabled on the domain, deploy stops and asks you to enable it in the dashboard first.

Install

Install the package globally to use the mm command anywhere:

bash
npm install -g mailmask

Or run it without installing:

bash
npx mailmask

mailmask and mm are the same command. The first run copies a starter config.json into your platform config directory, so you don't need to clone the repository.

First-Time Setup

Run mm with no arguments to open the interactive menu, then work through these steps.

  1. Open Settings. Set the Worker name and the email domain, which becomes your base domain (for example mail.example.com).
  2. Add a destination. Under Manage Destinations, give your real inbox a short name like personal and enter its address.
  3. Create an alias. Under Manage Aliases, choose Create, pick an address style, and choose the destination to forward to.
  4. Deploy. Choose Deploy and paste a Cloudflare API token when asked.

The same steps work as direct commands:

bash
# Add your real inbox.
mm destination add personal you@example.com

# Create a memorable alias that forwards to it.
mm alias add -d personal -l "Online shopping"

# Validate, register the inbox, deploy, and point the catch-all at the Worker.
mm deploy

Verify Your Inbox

On the first deploy, Cloudflare sends a verification email to each new destination. Mail for an alias can't reach that inbox until you click the link in that email.

tip

Run mm deploy again after verifying. The summary confirms that every destination is verified and lists each alias with its full address.

Send a Test Message

Send an email from any account to the address the CLI printed, such as velvet-harbor-42@mail.example.com. It arrives in your real inbox within a few seconds.

When alias headers are enabled, the forwarded message carries X-Mailmask-Alias and X-Mailmask-Label headers. You can use them to build filters in your mail client.

If Something Goes Wrong

Check Troubleshooting for the most common first-run problems:

  • Email Routing not enabled on the domain.
  • A destination that has not been verified yet.
  • An API token missing one of the three required permissions.

What Is Next