title: "lists" description: "Manage allow and block lists for the organization, a pod or an inbox from the MachineMail CLI: create, get, list and delete entries, with flags and examples." canonical: "https://machinemail.dev/docs/cli/commands/lists"

lists

Manage allow and block lists for the organization, a pod or an inbox from the MachineMail CLI: create, get, list and delete entries, with flags and examples.

Source: https://machinemail.dev/docs/cli/commands/lists

Allow and block lists for the organization, a pod or an inbox. A non-empty allow list is allow-only: one receive/allow entry blocks mail from every sender not on it.

Every command also takes the global flags.

lists create

Create list entry.

An address (user@example.com) or a domain (example.com); a domain also matches its subdomains. Adding an entry that exists returns it unchanged.

An allow entry makes its scope allow-only. The first receive/allow entry at the organization (/v0/lists), a pod (/v0/pods/{pod_id}/lists) or an inbox (/v0/inboxes/{inbox_id}/lists) blocks every sender that does not match an allow entry: their mail is labeled BLOCKED, emits message.received.blocked and is withheld from agents. Likewise, a send/allow entry blocks sending to every other recipient. An allow-listed sender reaches trust level verified only when DMARC passes and is aligned; do not add one only to raise trust. Prior correspondence (an inbox in the organization has written to the sender) is the usual way to reach verified.

Requires the list_entry_create permission.

machinemail lists create <direction> <type> [flags]

Arguments

Flags

Examples

machinemail lists create send allow --entry spam@example.com
machinemail lists create send allow --entry spam@example.com --inbox agent@machinemail.dev
machinemail lists create send allow --data @body.json

API

• POST /v0/lists/{direction}/{type}
• POST /v0/inboxes/{inbox_id}/lists/{direction}/{type} with --inbox
• POST /v0/pods/{pod_id}/lists/{direction}/{type} with --pod

lists delete

Delete list entry.

Also: machinemail lists rm.

Deleting the last allow entry for a direction at every level that applies ends allow-only mode: unmatched addresses are allowed again unless a block entry matches.

Requires the list_entry_delete permission.

machinemail lists delete <direction> <type> <entry> [flags]

Arguments

Flags

Examples

machinemail lists delete send allow spam@example.com
machinemail lists delete send allow spam@example.com --inbox agent@machinemail.dev

API

• DELETE /v0/lists/{direction}/{type}/{entry}
• DELETE /v0/inboxes/{inbox_id}/lists/{direction}/{type}/{entry} with --inbox
• DELETE /v0/pods/{pod_id}/lists/{direction}/{type}/{entry} with --pod

lists get

Get list entry.

Requires the list_entry_read permission.

machinemail lists get <direction> <type> <entry> [flags]

Arguments

Flags

Examples

machinemail lists get send allow spam@example.com
machinemail lists get send allow spam@example.com --inbox agent@machinemail.dev

API

• GET /v0/lists/{direction}/{type}/{entry}
• GET /v0/inboxes/{inbox_id}/lists/{direction}/{type}/{entry} with --inbox
• GET /v0/pods/{pod_id}/lists/{direction}/{type}/{entry} with --pod

lists list

List the entries of an allow or block list.

Also: machinemail lists ls.

Entries stored at this exact level. Mail is checked against the organization, pod and inbox lists together. An allow entry wins over a block entry; while any allow entry exists for a direction, every address that matches none is blocked (allow-only).

Requires the list_entry_read permission.

machinemail lists list <direction> <type> [flags]

Arguments

Flags

Examples

machinemail lists list send allow
machinemail lists list send allow --inbox agent@machinemail.dev
machinemail lists list send allow --all --json | jq '.entries | length'

API

• GET /v0/lists/{direction}/{type}
• GET /v0/inboxes/{inbox_id}/lists/{direction}/{type} with --inbox
• GET /v0/pods/{pod_id}/lists/{direction}/{type} with --pod