fastmask

Python library and command line tool for Fastmail's Masked Email

Install & Setup

pip install fastmask

export FM_ME_TOKEN='YOUR-API-TOKEN-HERE'
export FM_USERNAME='user@domain.com'

Usage

fastmask [OPTIONS] COMMAND [ARGS]...

  Manage Fastmail masked email from the command line

Options:
  --version        Show the version and exit.
  --username TEXT  [default: (FM_USERNAME)]
  --token TEXT     [default: (FM_ME_TOKEN)]
  --help           Show this message and exit.

Commands:
  activate  Set state of masked email to Active
  block     Set state of masked email to Blocked
  delete    Delete masked email
  edit      Edit information associated with a masked email
  list      List masked emails associated with account
  new       Create a new masked email
  search    Search for masked emails

Authentication

You will need to provide an API token for fastmask to authenticate calls to the Fastmail API:

1. In the Fastmail web client, go to Settings > Account > Password & Security > API Tokens > Manage > New API token
2. Set name to "fastmask" or whatever you'd like, check only the Masked Email scope and hit Generate API token
3. Copy the API token. You can authenticate either by providing your credentials as arguments, or by using the FM_ME_TOKEN and FM_USERNAME environment variables / providing these variables via .env file:

Example:

export FM_ME_TOKEN='YOUR-TOKEN-HERE'
export FM_USERNAME='username@fastmail.com'

fastmask list --limit 5

# alternatively, you can provide your credentials as arguments
fastmask --username username@fastmail.com --token 'YOUR-TOKEN-HERE' \
  list --limit 5

Create a masked email

Use fastmask new to create a new masked email address. Optionally specifiy the description, URL or domain.

Example:

fastmask new twitter --url twitter.com

> Successfully added email fake.email1234@fastmail.com (id: masked-12345678)

List

fastmask list will return a Rich table, json, or csv of masked emails, optionally filtering results by active/blocked state, recent, used/unused status, etc.

Usage:

fastmask list [OPTIONS]

  List masked emails associated with account

Options:
  --limit INTEGER                 Limit number of results
  --active                        Show only active addresses
  --blocked                       Show only blocked addresses
  --unused                        Show only active + unused addresses
  --used                          Show only used addresses
  --deleted                       Show only deleted addresses
  --sort                          Field to sort by
  --desc / --asc                  Sort order
  --recent INTEGER                Only show items from the past X days
  -j, --json                      Print to json instead of table
  -o, --out TEXT                  Output to csv or json file
  --help                          Show this message and exit.

Examples:

fastmask list --unused

fastmask list --blocked --limit 20 --json

fastmask list --sort lastMessageAt --desc --active

Activate / Block / Delete

You can change the state of a masked email with fastmask activate, fastmask block or fastmask delete. Email IDs accepted are:

• email address
• description (case-insensitive)
• the id of the address, with or without the "masked-" prefix

Examples:

fastmask activate new.mail0412@fastmail.com

fastmask block masked-12312345

fastmask delete facebook.com

Edit

fastmask edit can be used to change the description, url or domain associated with masked email address.

Example:

fastmask edit some.user1231@fastmail.com --description x.com --url x.com

Search

fastmask search is a case-insensitive search defaulting to matching email addresses and descriptions. You can set the fields searches using the --field flag.

Examples:

fastmask search reddit

fastmask search --field email fastmail.com

fastmask search --field createdAt 2022-10-31

fastmask search --field createdBy fastmask -o out.csv

See full CLI and library documentation at https://fastmask.readthedocs.io/