## lists create 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`](/content/docs/cli/commands/lists#lists-create/index.html) | Create list entry | | [`lists delete`](/content/docs/cli/commands/lists#lists-delete/index.html) | Delete list entry | | [`lists get`](/content/docs/cli/commands/lists#lists-get/index.html) | Get list entry | | [`lists list`](/content/docs/cli/commands/lists#lists-list/index.html) | List the entries of an allow or block list | Every command also takes the [global flags](/content/docs/cli/commands#global-flags/index.html). ## 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. ```shell machinemail lists create [flags] ``` ### Arguments | Field | 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 | 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 ```shell 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}`](/content/docs/reference/api/lists#create-list-entry/index.html) - [`POST /v0/inboxes/{inbox_id}/lists/{direction}/{type}`](/content/docs/reference/api/lists#create-list-entry-in-inbox/index.html) with `--inbox` - [`POST /v0/pods/{pod_id}/lists/{direction}/{type}`](/content/docs/reference/api/lists#create-list-entry-in-pod/index.html) 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. ```shell machinemail lists delete [flags] ``` ### Arguments | Field | 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 | Description | | --- | --- | | `--inbox ` | `string` Use this inbox's scoped route. | | `--pod ` | `string` Use this pod's scoped route. | ### Examples ```shell 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}`](/content/docs/reference/api/lists#delete-list-entry/index.html) - [`DELETE /v0/inboxes/{inbox_id}/lists/{direction}/{type}/{entry}`](/content/docs/reference/api/lists#delete-list-entry-in-inbox/index.html) with `--inbox` - [`DELETE /v0/pods/{pod_id}/lists/{direction}/{type}/{entry}`](/content/docs/reference/api/lists#delete-list-entry-in-pod/index.html) with `--pod` ## lists get Get list entry. Requires the list_entry_read permission. ```shell machinemail lists get [flags] ``` ### Arguments ### Flags | Field | Description | | --- | --- | | `--inbox ` | `string` Only this inbox. | | `--pod ` | `string` Only this pod. | ### Examples ```shell 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}`](/content/docs/reference/api/lists#get-list-entry/index.html) - [`GET /v0/inboxes/{inbox_id}/lists/{direction}/{type}/{entry}`](/content/docs/reference/api/lists#get-list-entry-in-inbox/index.html) with `--inbox` - [`GET /v0/pods/{pod_id}/lists/{direction}/{type}/{entry}`](/content/docs/reference/api/lists#get-list-entry-in-pod/index.html) 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. ```shell machinemail lists list [flags] ``` ### Arguments ### Flags | Field | 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 ```shell 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}`](/content/docs/reference/api/lists/index.html) - [`GET /v0/inboxes/{inbox_id}/lists/{direction}/{type}`](/content/docs/reference/api/lists#list-entries-in-inbox/index.html) with `--inbox` - [`GET /v0/pods/{pod_id}/lists/{direction}/{type}`](/content/docs/reference/api/lists#list-entries-in-pod/index.html) with `--pod`