--- 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. | Command | Summary | | ------------------------------- | ------------------------------------------ | | [`lists create`](#lists-create) | Create list entry | | [`lists delete`](#lists-delete) | Delete list entry | | [`lists get`](#lists-get) | Get list entry | | [`lists list`](#lists-list) | List the entries of an allow or block list | Every command also takes the [global flags](https://machinemail.dev/docs/cli/commands#global-flags). ## lists create Create list entry. An address ([user@example.com](mailto: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. ```bash machinemail lists create [flags] ``` #### Arguments | Field | Type | | Description | | --- | --- | --- | --- | | `` | `string` | required | receive: who may send to you (inbound mail from a blocked sender is labeled BLOCKED). send: who you may send to (a blocked recipient is a 403). reply entries are stored and listed but not applied to any mail yet. | | `` | `string` | required | block refuses matching addresses. allow makes the list exclusive: once it has an entry, only matching addresses pass. | #### Flags | Field | Type | | Description | | --- | --- | --- | --- | | `--inbox ` | `string` | | Create it in this inbox. | | `--pod ` | `string` | | Create it in this pod. | | `--entry ` | `string` | | Email address or domain to add. | | `--reason ` | `string` | | Reason for adding the entry. | | `-d, --data ` | `string` | | Request body as JSON, @file or - for stdin; field flags override its keys. | #### Examples ```bash 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}`](https://machinemail.dev/docs/reference/api/lists#create-list-entry) - [`POST /v0/inboxes/{inbox_id}/lists/{direction}/{type}`](https://machinemail.dev/docs/reference/api/lists#create-list-entry-in-inbox) with `--inbox` - [`POST /v0/pods/{pod_id}/lists/{direction}/{type}`](https://machinemail.dev/docs/reference/api/lists#create-list-entry-in-pod) 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. ```bash machinemail lists delete [flags] ``` #### Arguments | Field | Type | | Description | | --- | --- | --- | --- | | `` | `string` | required | receive: who may send to you (inbound mail from a blocked sender is labeled BLOCKED). send: who you may send to (a blocked recipient is a 403). reply entries are stored and listed but not applied to any mail yet. | | `` | `string` | required | block refuses matching addresses. allow makes the list exclusive: once it has an entry, only matching addresses pass. | | `` | `string` | required | Email address or domain. | #### Flags | Field | Type | | Description | | --- | --- | --- | --- | | `--inbox ` | `string` | | Use this inbox's scoped route. | | `--pod ` | `string` | | Use this pod's scoped route. | #### Examples ```bash 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}`](https://machinemail.dev/docs/reference/api/lists#delete-list-entry) - [`DELETE /v0/inboxes/{inbox_id}/lists/{direction}/{type}/{entry}`](https://machinemail.dev/docs/reference/api/lists#delete-list-entry-in-inbox) with `--inbox` - [`DELETE /v0/pods/{pod_id}/lists/{direction}/{type}/{entry}`](https://machinemail.dev/docs/reference/api/lists#delete-list-entry-in-pod) with `--pod` ## lists get Get list entry. Requires the list\_entry\_read permission. ```bash machinemail lists get [flags] ``` #### Arguments | Field | Type | | Description | | --- | --- | --- | --- | | `` | `string` | required | receive: who may send to you (inbound mail from a blocked sender is labeled BLOCKED). send: who you may send to (a blocked recipient is a 403). reply entries are stored and listed but not applied to any mail yet. | | `` | `string` | required | block refuses matching addresses. allow makes the list exclusive: once it has an entry, only matching addresses pass. | | `` | `string` | required | Email address or domain. | #### Flags | Field | Type | | Description | | --- | --- | --- | --- | | `--inbox ` | `string` | | Only this inbox. | | `--pod ` | `string` | | Only this pod. | #### Examples ```bash 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}`](https://machinemail.dev/docs/reference/api/lists#get-list-entry) - [`GET /v0/inboxes/{inbox_id}/lists/{direction}/{type}/{entry}`](https://machinemail.dev/docs/reference/api/lists#get-list-entry-in-inbox) with `--inbox` - [`GET /v0/pods/{pod_id}/lists/{direction}/{type}/{entry}`](https://machinemail.dev/docs/reference/api/lists#get-list-entry-in-pod) 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. ```bash machinemail lists list [flags] ``` #### Arguments | Field | Type | | Description | | --- | --- | --- | --- | | `` | `string` | required | receive: who may send to you (inbound mail from a blocked sender is labeled BLOCKED). send: who you may send to (a blocked recipient is a 403). reply entries are stored and listed but not applied to any mail yet. | | `` | `string` | required | block refuses matching addresses. allow makes the list exclusive: once it has an entry, only matching addresses pass. | #### Flags | Field | Type | | Description | | --- | --- | --- | --- | | `--inbox ` | `string` | | Only this inbox. | | `--pod ` | `string` | | Only this pod. | | `--limit ` | `integer` | | Maximum number of items to return. Default 50, maximum 500; larger values are capped. Default: `50`. | | `--page-token ` | `string` | | next_page_token from the previous page. | | `--ascending` | `boolean` | | false sorts by entry descending. Default true. Default: `true`. | | `--all` | `boolean` | | Follow next_page_token and return every page. | #### Examples ```bash 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}`](https://machinemail.dev/docs/reference/api/lists) - [`GET /v0/inboxes/{inbox_id}/lists/{direction}/{type}`](https://machinemail.dev/docs/reference/api/lists#list-entries-in-inbox) with `--inbox` - [`GET /v0/pods/{pod_id}/lists/{direction}/{type}`](https://machinemail.dev/docs/reference/api/lists#list-entries-in-pod) with `--pod`