Mail access with the mazemail CLI

mazemail talks to the running Maze app over a local socket; it never opens the mail store itself. Every command prints a readable table on a terminal and stable JSON with --json. Ids are short and stable: m_… message, t_… thread, d_… draft, f_… folder, a_… account, tk_… token.

Signing in

• Commands that touch mail need a session token in MAZEMAIL_SESSION. Agents started by Maze already have one.
• Otherwise run eval "$(mazemail login --profile read-only --ttl 8h)". Maze shows which program is asking and waits for approval (“waiting for approval in Maze…”).
• Without a token only mazemail help, mazemail status and mazemail login work (exit code 6).
• Your token decides what you can do (see the table below) and which accounts and folders you can see. Accounts whose AI policy excludes agents are never visible.

Exit codes

What each profile may do

allow runs directly, propose becomes a proposal you review in Maze, ask waits for approval in Maze, deny fails with exit code 3.

Permanent delete is not available to tokens. send is disabled unless the token was approved with --allow-send, and then every send asks.

Commands

mazemail status

Show whether Maze is running and whether you are signed in.

Shows Maze’s version and protocol, and the current token’s profile, scope and expiry. Works without a token.

Permission: read (works without a token)

mazemail status

Output (--json):

{
  app: any,  // Details from the app (accounts, sync state; only when signed in).
  protocol: integer,  // Protocol major version.
  running: boolean,  // Always `true` (otherwise the CLI exits with code 5).
  signed_in: boolean,  // Whether the request carried a valid token.
  token?: {
    allow_send: boolean,  // Whether `send` is enabled (always asks).
    created_at: string,  // Creation time (RFC 3339).
    created_by: {
      kind: "user",
    }
    | {
      kind: "session",
      session: string,  // The agent session's id.
    },  // Who created it.
    expires_at?: string | null,  // Expiry (RFC 3339), `null` = never.
    id: string,  // Public id (`tk_…`).
    label?: string | null,  // Label.
    profile: "read-only" | "triage" | "writer",  // Profile.
    revoked: boolean,  // Whether it was revoked.
    scope: {
      accounts?: string[] | null,  // Account ids (`a_…`), or `null` for all.
      folders?: string[] | null,  // Folder ids (`f_…`), or `null` for all.
    },  // Accounts and folders (`null` = all).
  }
  | null,  // The token, when signed in.
  token_error?: string | null,  // Why a presented token was not accepted ("the session token has expired").
  version: string,  // Maze's version.
}

Examples:

# Check the session
mazemail status --json | jq .signed_in

mazemail help

List commands and what your token may do with them.

Without a topic, lists every command with its permission and what happens with your token (allow, propose, ask or deny). mazemail help <command> shows a command’s help, mazemail help agents prints this AGENTS.md. Works without a token.

Permission: read (works without a token)

mazemail help [<TOPIC>...]

Output (--json):

{
  commands: [
    {
      access?: "allow" | "propose" | "ask" | "deny" | null,  // What happens with the caller's token (`null` without a token).
      command: string,  // As typed after `mazemail` (`draft new`).
      permission: "read" | "draft" | "propose" | "ask" | "disabled" | "admin",  // Permission class.
      requires_token: boolean,  // Whether the command needs a token.
      summary: string,  // One-line summary.
    }
  ],  // Every command.
}

Examples:

# Help for one command
mazemail help draft new
# Write the agent guide
mazemail help agents > AGENTS.md

mazemail login

Ask Maze for a session token.

Maze shows which program is asking, the profile, scope and lifetime, and waits for your approval. Approved, it prints export MAZEMAIL_SESSION=… for the current shell. A program that already holds a token still needs approval, and the new token gets exactly what you approve. Accounts whose AI policy excludes agents are never in a token’s scope.

Permission: ask (works without a token)

mazemail login [OPTIONS]

Output (--json):

{
  allow_send: boolean,  // Whether `send` is enabled (always asks).
  expires_at?: string | null,  // Expiry (RFC 3339).
  export: string,  // `export MAZEMAIL_SESSION=…`, for `eval "$(mazemail login)"`.
  id: string,  // The token's public id.
  profile: "read-only" | "triage" | "writer",  // The approved profile.
  scope: {
    accounts?: string[] | null,  // Account ids (`a_…`), or `null` for all.
    folders?: string[] | null,  // Folder ids (`f_…`), or `null` for all.
  },  // The approved scope (`null` = all).
  token: string,  // The new token. Shown once; Maze keeps only a hash.
}

Examples:

# Sign in the current shell
eval "$(mazemail login --profile read-only --ttl 8h)"
# A triage token for one account
mazemail login --profile triage --account a_b --label claude

mazemail token create

Ask Maze for a session token (same as mazemail login).

An alias of mazemail login.

Permission: ask (works without a token)

mazemail token create [OPTIONS]

Output (--json):

{
  allow_send: boolean,  // Whether `send` is enabled (always asks).
  expires_at?: string | null,  // Expiry (RFC 3339).
  export: string,  // `export MAZEMAIL_SESSION=…`, for `eval "$(mazemail login)"`.
  id: string,  // The token's public id.
  profile: "read-only" | "triage" | "writer",  // The approved profile.
  scope: {
    accounts?: string[] | null,  // Account ids (`a_…`), or `null` for all.
    folders?: string[] | null,  // Folder ids (`f_…`), or `null` for all.
  },  // The approved scope (`null` = all).
  token: string,  // The new token. Shown once; Maze keeps only a hash.
}

Examples:

# Print just the token
mazemail token create --profile read-only --ttl 1h --json | jq -r .token

mazemail token list

List API tokens.

Lists every token with its profile, scope, expiry and creator. Secrets are never shown; Maze only keeps hashes.

Permission: read

mazemail token list

Output (--json):

[
  {
    allow_send: boolean,  // Whether `send` is enabled (always asks).
    created_at: string,  // Creation time (RFC 3339).
    created_by: {
      kind: "user",
    }
    | {
      kind: "session",
      session: string,  // The agent session's id.
    },  // Who created it.
    expires_at?: string | null,  // Expiry (RFC 3339), `null` = never.
    id: string,  // Public id (`tk_…`).
    label?: string | null,  // Label.
    profile: "read-only" | "triage" | "writer",  // Profile.
    revoked: boolean,  // Whether it was revoked.
    scope: {
      accounts?: string[] | null,  // Account ids (`a_…`), or `null` for all.
      folders?: string[] | null,  // Folder ids (`f_…`), or `null` for all.
    },  // Accounts and folders (`null` = all).
  }
]

Examples:

# Show tokens
mazemail token list

mazemail token revoke

Revoke an API token.

Revoking your own token (the one in MAZEMAIL_SESSION) always works. Revoking another token asks for approval in Maze.

Permission: ask

mazemail token revoke <TOKEN_ID>

Output (--json):

{
  id: string,  // The token's id.
  revoked: boolean,  // `false` if it was already revoked.
}

Examples:

# Revoke a token
mazemail token revoke tk_q3x7k2mz4b5ca

mazemail search

Search mail.

Searches every account and folder in your token’s scope, newest first. The query language is Thunderbird’s quick filter plus Gmail-style operators.

Permission: read

mazemail search [OPTIONS] <QUERY>

Output (--json):

[
  {
    account: string,  // Account id.
    date: string,  // Date (RFC 3339).
    flagged: boolean,  // Flagged.
    folder?: string | null,  // Folder id.
    from: string,  // Sender ("Name <address>").
    has_attachments: boolean,  // Has attachments.
    id: string,  // Message id.
    snippet?: string | null,  // Start of the body.
    subject: string,  // Subject.
    tags: string[],  // Tag names.
    thread: string,  // Thread id.
    unread: boolean,  // Unread.
  }
]

Examples:

# Thread of the newest match
mazemail search 'from:anna has:attachment after:2026-09-01' --json | jq -r '.[0].thread'
# Ten unread messages
mazemail search 'is:unread' --limit 10

mazemail show

Show a message or a whole thread.

Renders a message (m_…) or a thread (t_…, all messages oldest first) as Markdown, plain text or the raw message. Remote content is never loaded.

Permission: read

mazemail show [OPTIONS] <ID>

Output (--json):

{
  content: string,  // The message or whole thread rendered in `format`.
  format: "md" | "text" | "raw",  // Format of `content`.
  id: string,  // The requested message or thread id.
  messages: [
    {
      attachments: [
        {
          content_type: string,  // MIME type.
          filename: string,  // File name.
          id: string,  // Attachment id, for `mazemail attachment save`.
          size: integer,  // Size in bytes.
        }
      ],  // Attachments.
      date: string,  // Date (RFC 3339).
      from: string,  // Sender.
      id: string,  // Message id.
      subject: string,  // Subject.
      to: string[],  // Recipients.
    }
  ],  // The messages shown, oldest first.
  thread: string,  // Thread id.
}

Examples:

# A thread as Markdown
mazemail show t_19bd --format md
# Save the raw message
mazemail show m_8f3a2c --format raw > message.eml

mazemail folders

List folders.

Lists the folders in your token’s scope with unread and total counts.

Permission: read

mazemail folders [OPTIONS]

Output (--json):

[
  {
    account: string,  // Account id.
    id: string,  // Folder id.
    name: string,  // Display name.
    path: string,  // Full path (`Archive/2026`).
    role?: string | null,  // Special-use role (`inbox`, `sent`, `drafts`, `trash`, `junk`, `archive`, …).
    total: integer,  // All messages.
    unread: integer,  // Unread messages.
  }
]

Examples:

# Find the archive folders
mazemail folders --json | jq -r '.[] | select(.role == "archive") | .id'

mazemail tags

List tags.

Lists tags (IMAP keywords) with their colors.

Permission: read

mazemail tags

Output (--json):

[
  {
    color?: string | null,  // Color (`#rrggbb`).
    id: string,  // Tag id.
    name: string,  // Name.
  }
]

Examples:

# Show tags
mazemail tags

mazemail contacts

Find contacts.

Finds people you have exchanged mail with by name or address.

Permission: read

mazemail contacts [OPTIONS] <QUERY>

Output (--json):

[
  {
    email: string,  // Address.
    name?: string | null,  // Display name.
  }
]

Examples:

# Find Anna's address
mazemail contacts anna

mazemail identities

List your sending identities.

Lists the identities (From addresses) of the accounts in scope. draft new picks one automatically when you don’t pass –identity.

Permission: read

mazemail identities [OPTIONS]

Output (--json):

[
  {
    account: string,  // Account id.
    default: boolean,  // The account's default identity.
    email: string,  // Address.
    id: string,  // Identity id.
    name: string,  // Display name.
  }
]

Examples:

# Show identities
mazemail identities

mazemail attachment save

Save an attachment to a file.

Writes the attachment into –to (default: the current directory) under its sanitized file name, never overwriting an existing file.

Permission: read

mazemail attachment save [OPTIONS] <ID>

Output (--json):

{
  content_type: string,  // MIME type.
  id: string,  // Attachment id.
  path: string,  // Where the file was written.
  size: integer,  // Size in bytes.
}

Examples:

# Save into the current directory
mazemail attachment save m_8f3a2c.2 --to .

mazemail draft new

Write a new draft, reply or forward.

Creates a draft in Maze for you to review and send. Drafts are harmless: nothing is sent. The identity is picked automatically from the recipients and the replied-to message unless you pass –identity.

Permission: draft

mazemail draft new [OPTIONS]

Output (--json):

{
  id: string,  // Draft id.
  identity?: string | null,  // The identity it is written from.
  subject: string,  // Subject.
  to: string[],  // Recipients.
}

Examples:

# Reply; identity picked automatically
mazemail draft new --reply-to m_8f3a2c --body-file reply.md
# New message with the body from stdin
echo 'See you then.' | mazemail draft new --to anna@example.com --subject Friday --body-file -

mazemail draft edit

Change a draft.

Replaces the given fields of a draft; everything else stays as it is.

Permission: draft

mazemail draft edit [OPTIONS] <ID>

Output (--json):

{
  id: string,  // Draft id.
  identity?: string | null,  // The identity it is written from.
  subject: string,  // Subject.
  to: string[],  // Recipients.
}

Examples:

# Replace subject and body
mazemail draft edit d_42 --subject 'Re: Friday' --body-file reply.md

mazemail archive

Archive messages or threads.

Under the triage profile this becomes a proposal that you accept or reject in Maze’s review UI; under the writer profile it runs directly.

Permission: propose

mazemail archive <ID>...

Output (--json):

{
  affected: string[],  // Message ids affected.
  outcome: "applied" | "proposed",  // Applied directly, or a proposal.
  proposal?: string | null,  // The proposal's id, if proposed.
}

Examples:

# Archive old newsletters (a proposal under triage)
mazemail archive $(mazemail search 'list:news older_than:7d' --ids)

mazemail move

Move messages or threads to a folder.

Under the triage profile this becomes a proposal that you accept or reject in Maze’s review UI; under the writer profile it runs directly.

Permission: propose

mazemail move --to <FOLDER> <ID>...

Output (--json):

{
  affected: string[],  // Message ids affected.
  outcome: "applied" | "proposed",  // Applied directly, or a proposal.
  proposal?: string | null,  // The proposal's id, if proposed.
}

Examples:

# Move to a folder
mazemail move --to f_k2 m_8f3a2c t_19bd

mazemail tag

Add or remove tags.

Under the triage profile this becomes a proposal that you accept or reject in Maze’s review UI; under the writer profile it runs directly.

Permission: propose

mazemail tag [OPTIONS] <ID>...

Output (--json):

{
  affected: string[],  // Message ids affected.
  outcome: "applied" | "proposed",  // Applied directly, or a proposal.
  proposal?: string | null,  // The proposal's id, if proposed.
}

Examples:

# Retag a message
mazemail tag --add 'To Do' --remove Later m_8f3a2c

mazemail flag

Flag or unflag messages.

Under the triage profile this becomes a proposal that you accept or reject in Maze’s review UI; under the writer profile it runs directly.

Permission: propose

mazemail flag [OPTIONS] <ID>...

Output (--json):

{
  affected: string[],  // Message ids affected.
  outcome: "applied" | "proposed",  // Applied directly, or a proposal.
  proposal?: string | null,  // The proposal's id, if proposed.
}

Examples:

# Flag a message
mazemail flag m_8f3a2c

mazemail read

Mark messages read or unread.

Under the triage profile this becomes a proposal that you accept or reject in Maze’s review UI; under the writer profile it runs directly.

Permission: propose

mazemail read [OPTIONS] <ID>...

Output (--json):

{
  affected: string[],  // Message ids affected.
  outcome: "applied" | "proposed",  // Applied directly, or a proposal.
  proposal?: string | null,  // The proposal's id, if proposed.
}

Examples:

# Mark a thread unread
mazemail read --unread t_19bd

mazemail propose

Propose a batch of actions for review.

Sends a list of actions (archive, move, tag, flag, mark_read, unsubscribe) that shows up grouped in Maze’s review UI, where you accept or reject each item. Nothing changes until you accept.

Permission: draft

mazemail propose [OPTIONS] --file <FILE>

Output (--json):

{
  items: integer,  // Number of items.
  proposal: string,  // The proposal's id.
}

Examples:

# Propose actions from a file
mazemail propose --title 'Inbox triage' --file actions.json

mazemail rule add

Add a filter rule.

Adds a rule that runs on new mail. Always asks for approval in Maze.

Permission: ask

mazemail rule add [OPTIONS] --name <NAME> --when <QUERY> --then <ACTION>...

Output (--json):

{
  id: string,  // Rule id.
  name: string,  // Name.
}

Examples:

# Tag and archive receipts
mazemail rule add --name Receipts --when 'from:receipts@shop.example' --then tag:Receipts --then archive

mazemail send

Send a draft.

Disabled by default. A token approved with –allow-send may use it, and then every send waits for your approval in Maze (“waiting for approval in Maze…”) and is never approved automatically.

Permission: disabled

mazemail send <DRAFT>

Output (--json):

{
  draft: string,  // The sent draft.
  outbox: string,  // Outbox item id (sending happens in the background).
}

Examples:

# Send after approval
mazemail send d_42

mazemail export

Export messages to mbox or Maildir.

Writes the matching messages as plaintext to –to. Always asks for approval in Maze, because the export leaves encrypted storage.

Permission: ask

mazemail export [OPTIONS] --to <PATH> <QUERY>

Output (--json):

{
  messages: integer,  // Messages exported.
  path: string,  // Where the export was written.
}

Examples:

# Export this year's inbox
mazemail export 'in:inbox after:2026-01-01' --to inbox.mbox

mazemail import

Import an mbox file, a Maildir or a Thunderbird profile.

Uploads mbox and Maildir mail into a folder of an IMAP account (–account, –folder; the folder is created if missing), queued and sent by the sync engine; it shows up after the folder’s next sync. Messages the folder already has are skipped. A Thunderbird profile brings its IMAP accounts, identities, tags, filters, saved searches and address books; POP3 accounts and Local Folders are skipped (Maze is IMAP only). Always asks for approval in Maze.

Permission: ask

mazemail import [OPTIONS] <PATH>

Output (--json):

{
  accounts: integer,  // Accounts created (Thunderbird profiles).
  duplicates: integer,  // Messages skipped because the folder already has them or they are queued.
  folders: integer,  // Folders created.
  messages: integer,  // Messages queued for upload to the server (mbox, Maildir).
  skipped: string[],  // What wasn't imported and why ("POP3 account x@y skipped: …").
}

Examples:

# Upload an mbox file into a folder of your account
mazemail import ~/old-mail.mbox --account a_b --folder Archive/2019
# Import a Thunderbird profile
mazemail import ~/Library/Thunderbird/Profiles/abcd.default-release

mazemail account list

List mail accounts and their sync state.

Lists the accounts in your token’s scope with their server, sign-in method and sync state (up to date, syncing, offline, sign-in required).

Permission: read

mazemail account list

Output (--json):

[
  {
    auth?: string | null,  // `password`, `oauth:google` or `oauth:microsoft`, for synced accounts.
    email?: string | null,  // The address, if known.
    id: string,  // Account id.
    kind: string,  // `imap`, `gmail`, `m365` or `local`.
    name: string,  // The name in the folder pane.
    server?: string | null,  // The IMAP server (`host:port`), for synced accounts.
    state: string,  // `connecting`, `idle`, `syncing`, `offline`, `auth_required`, `error` or `not_synced`.
    status: string,  // The sync state as a sentence.
  }
]

Examples:

# Accounts that need a new sign-in
mazemail account list --json | jq -r '.[] | select(.state == "auth_required") | .id'

mazemail account add

Add an IMAP, Gmail or Microsoft account.

Maze connects, logs in and lists the folders before it saves anything, then keeps the password (or the sign-in) in its encrypted storage and starts syncing. The password is read from the terminal without echo, or from stdin with –password-stdin; it is never a command-line argument. With –oauth google or –oauth microsoft, Maze opens the browser for the sign-in instead (Google needs auth.google.client_id in settings.json). Microsoft sign-ins use the auth.microsoft.tenant setting (default common); –tenant overrides it for this account, e.g. with your organization’s tenant ID or domain when its app registration only allows its own accounts. Host, port and security are detected for well-known providers; so is the SMTP server for sending (override it with –smtp-host, –smtp-port and –smtp-security; it logs in like IMAP). Needs a writer token, and you approve every account in Maze.

Permission: admin

mazemail account add [OPTIONS] <EMAIL>

Output (--json):

{
  auth?: string | null,  // `password`, `oauth:google` or `oauth:microsoft`, for synced accounts.
  email?: string | null,  // The address, if known.
  id: string,  // Account id.
  kind: string,  // `imap`, `gmail`, `m365` or `local`.
  name: string,  // The name in the folder pane.
  server?: string | null,  // The IMAP server (`host:port`), for synced accounts.
  state: string,  // `connecting`, `idle`, `syncing`, `offline`, `auth_required`, `error` or `not_synced`.
  status: string,  // The sync state as a sentence.
}

Examples:

# Add an account; asks for the password
mazemail account add alice@example.org --host imap.example.org
# Password from stdin (scripts)
printf '%s\n' "$PASSWORD" | mazemail account add alice@example.org --password-stdin
# Sign in with Google in the browser
mazemail account add bob@gmail.com --oauth google
# Sign in with Microsoft, for one organization (tenant)
mazemail account add dana@contoso.com --oauth microsoft --tenant contoso.com

mazemail account remove

Remove a mail account.

Stops syncing the account and deletes its local mail, folders, identities and saved password or sign-in. Nothing changes on the server. Needs a writer token, and you approve it in Maze.

Permission: admin

mazemail account remove <ACCOUNT>

Output (--json):

{
  id: string,  // The removed account's id.
  removed: boolean,  // Always `true`.
}

Examples:

# Remove an account
mazemail account remove a_b

mazemail sync

Sync accounts now.

Asks every account in your token’s scope (or –account) to look for new mail and replay pending changes now, and retries at once when an account is offline. Returns right away; mazemail account list shows the progress.

Permission: read

mazemail sync [OPTIONS]

Output (--json):

{
  accounts: string[],  // The accounts asked to sync now.
}

Examples:

# Sync every account
mazemail sync
# Sync one account
mazemail sync --account a_b