Skip to content
machinemail

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.

MethodPathSummary
GET/v0/inboxes/{inbox_id}/lists/{direction}/{type}List Entries in Inbox
POST/v0/inboxes/{inbox_id}/lists/{direction}/{type}Create List Entry in Inbox
GET/v0/inboxes/{inbox_id}/lists/{direction}/{type}/{entry}Get List Entry in Inbox
DELETE/v0/inboxes/{inbox_id}/lists/{direction}/{type}/{entry}Delete List Entry in Inbox
GET/v0/lists/{direction}/{type}List Entries
POST/v0/lists/{direction}/{type}Create List Entry
GET/v0/lists/{direction}/{type}/{entry}Get List Entry
DELETE/v0/lists/{direction}/{type}/{entry}Delete List Entry
GET/v0/pods/{pod_id}/lists/{direction}/{type}List Entries in Pod
POST/v0/pods/{pod_id}/lists/{direction}/{type}Create List Entry in Pod
GET/v0/pods/{pod_id}/lists/{direction}/{type}/{entry}Get List Entry in Pod
DELETE/v0/pods/{pod_id}/lists/{direction}/{type}/{entry}Delete List Entry in Pod

List Entries in Inbox

http
GET /v0/inboxes/{inbox_id}/lists/{direction}/{type}

Same as List Entries (GET /v0/lists/{direction}/{type}), limited to the inbox. While any allow entry applies for a direction, every address that matches none is blocked (allow-only).

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: list_entry_read.

Path parameters

inbox_idstringRequired
ID of the inbox.
direction"send" | "receive" | "reply"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.
type"allow" | "block"Required
block refuses matching addresses. allow makes the list exclusive: once it has an entry, only matching addresses pass.

Query parameters

limitinteger
Maximum number of items to return. Default 50, maximum 500; larger values are capped.
page_tokenstring
next_page_token from the previous page.
ascendingboolean
false sorts by entry descending. Default true.

Response

200 A page of entries (application/json)

countintegerRequired
Number of items returned.
limitinteger
Maximum number of items per page. Default 50, maximum 500; larger values are capped.
next_page_tokenstring
Page token for pagination. Absent on the last page.
entriesListEntry[]Required
Ordered by entry, ascending unless ascending is false.

Each item of entries is a ListEntry:

entrystringRequired
Email address or domain (lowercased).
organization_idstringRequired
ID of the organization.
pod_idstring
ID of the pod, for pod-scoped entries.
inbox_idstring
ID of the inbox, for inbox-scoped entries.
reasonstring
Reason given when the entry was added.
direction"send" | "receive" | "reply"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.
list_type"allow" | "block"Required
block refuses matching addresses. allow makes the list exclusive: once it has an entry, only matching addresses pass.
entry_type"email" | "domain"Required
Whether the entry is an email address or a domain.
read_onlybooleanRequired
Always false: every entry can be deleted through the API.
created_atstring (date-time)Required
Time at which the entry was created.

Errors

StatusMeaning
400Invalid request: error.type is validation and error.param names the field.
401Missing, invalid, expired or revoked credential.
403The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account_suspended: error.message says what still works; do not retry or re-register).
404Not found. Also returned for resources outside the credential scope.
500Unexpected server error.

Error bodies use the error envelope.

Example

Request
curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/lists/send/allow" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
Response 200
{
  "count": 1,
  "limit": 50,
  "next_page_token": "eyJvIjo1MH0",
  "entries": [
    {
      "entry": "customer@example.com",
      "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
      "pod_id": "pod_01k6x2m9qd0001b8j4mr0w3d5f",
      "inbox_id": "agent@machinemail.dev",
      "reason": "string",
      "direction": "send",
      "list_type": "allow",
      "entry_type": "email",
      "read_only": false,
      "created_at": "2026-10-01T12:00:00.000Z"
    }
  ]
}

Create List Entry in Inbox

http
POST /v0/inboxes/{inbox_id}/lists/{direction}/{type}

Same as Create List Entry (POST /v0/lists/{direction}/{type}), limited to the inbox. A receive/allow entry here makes this scope allow-only: mail from every sender that matches no allow entry is labeled BLOCKED and withheld from agents. An allow-listed sender reaches verified only with an aligned DMARC pass.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: list_entry_create.

Path parameters

inbox_idstringRequired
ID of the inbox.
direction"send" | "receive" | "reply"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.
type"allow" | "block"Required
block refuses matching addresses. allow makes the list exclusive: once it has an entry, only matching addresses pass.

Request body

Content type: application/json.

entrystringRequired
Email address or domain to add. (min length 1)
reasonstring
Reason for adding the entry.

Response

200 The entry (application/json)

entrystringRequired
Email address or domain (lowercased).
organization_idstringRequired
ID of the organization.
pod_idstring
ID of the pod, for pod-scoped entries.
inbox_idstring
ID of the inbox, for inbox-scoped entries.
reasonstring
Reason given when the entry was added.
direction"send" | "receive" | "reply"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.
list_type"allow" | "block"Required
block refuses matching addresses. allow makes the list exclusive: once it has an entry, only matching addresses pass.
entry_type"email" | "domain"Required
Whether the entry is an email address or a domain.
read_onlybooleanRequired
Always false: every entry can be deleted through the API.
created_atstring (date-time)Required
Time at which the entry was created.

Errors

StatusMeaning
400Invalid request: error.type is validation and error.param names the field.
401Missing, invalid, expired or revoked credential.
403The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account_suspended: error.message says what still works; do not retry or re-register).
404Not found. Also returned for resources outside the credential scope.
500Unexpected server error.

Error bodies use the error envelope.

Example

Request
curl -X POST "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/lists/send/allow" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "entry": "customer@example.com",
  "reason": "string"
}'
Response 200
{
  "entry": "customer@example.com",
  "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
  "pod_id": "pod_01k6x2m9qd0001b8j4mr0w3d5f",
  "inbox_id": "agent@machinemail.dev",
  "reason": "string",
  "direction": "send",
  "list_type": "allow",
  "entry_type": "email",
  "read_only": false,
  "created_at": "2026-10-01T12:00:00.000Z"
}

Get List Entry in Inbox

http
GET /v0/inboxes/{inbox_id}/lists/{direction}/{type}/{entry}

Same as Get List Entry (GET /v0/lists/{direction}/{type}/{entry}), limited to the inbox.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: list_entry_read.

Path parameters

inbox_idstringRequired
ID of the inbox.
direction"send" | "receive" | "reply"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.
type"allow" | "block"Required
block refuses matching addresses. allow makes the list exclusive: once it has an entry, only matching addresses pass.
entrystringRequired
Email address or domain.

Response

200 The entry (application/json)

entrystringRequired
Email address or domain (lowercased).
organization_idstringRequired
ID of the organization.
pod_idstring
ID of the pod, for pod-scoped entries.
inbox_idstring
ID of the inbox, for inbox-scoped entries.
reasonstring
Reason given when the entry was added.
direction"send" | "receive" | "reply"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.
list_type"allow" | "block"Required
block refuses matching addresses. allow makes the list exclusive: once it has an entry, only matching addresses pass.
entry_type"email" | "domain"Required
Whether the entry is an email address or a domain.
read_onlybooleanRequired
Always false: every entry can be deleted through the API.
created_atstring (date-time)Required
Time at which the entry was created.

Errors

StatusMeaning
401Missing, invalid, expired or revoked credential.
403The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account_suspended: error.message says what still works; do not retry or re-register).
404Not found. Also returned for resources outside the credential scope.
500Unexpected server error.

Error bodies use the error envelope.

Example

Request
curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/lists/send/allow/customer@example.com" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
Response 200
{
  "entry": "customer@example.com",
  "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
  "pod_id": "pod_01k6x2m9qd0001b8j4mr0w3d5f",
  "inbox_id": "agent@machinemail.dev",
  "reason": "string",
  "direction": "send",
  "list_type": "allow",
  "entry_type": "email",
  "read_only": false,
  "created_at": "2026-10-01T12:00:00.000Z"
}

Delete List Entry in Inbox

http
DELETE /v0/inboxes/{inbox_id}/lists/{direction}/{type}/{entry}

Same as Delete List Entry (DELETE /v0/lists/{direction}/{type}/{entry}), limited to the inbox.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: list_entry_delete.

Path parameters

inbox_idstringRequired
ID of the inbox.
direction"send" | "receive" | "reply"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.
type"allow" | "block"Required
block refuses matching addresses. allow makes the list exclusive: once it has an entry, only matching addresses pass.
entrystringRequired
Email address or domain.

Response

200 Deleted (application/json)

oktrueRequired

Errors

StatusMeaning
401Missing, invalid, expired or revoked credential.
403The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account_suspended: error.message says what still works; do not retry or re-register).
404Not found. Also returned for resources outside the credential scope.
500Unexpected server error.

Error bodies use the error envelope.

Example

Request
curl -X DELETE "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/lists/send/allow/customer@example.com" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
Response 200
{
  "ok": true
}

List Entries

http
GET /v0/lists/{direction}/{type}

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).

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: list_entry_read.

Path parameters

direction"send" | "receive" | "reply"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.
type"allow" | "block"Required
block refuses matching addresses. allow makes the list exclusive: once it has an entry, only matching addresses pass.

Query parameters

limitinteger
Maximum number of items to return. Default 50, maximum 500; larger values are capped.
page_tokenstring
next_page_token from the previous page.
ascendingboolean
false sorts by entry descending. Default true.

Response

200 A page of entries (application/json)

countintegerRequired
Number of items returned.
limitinteger
Maximum number of items per page. Default 50, maximum 500; larger values are capped.
next_page_tokenstring
Page token for pagination. Absent on the last page.
entriesListEntry[]Required
Ordered by entry, ascending unless ascending is false.

Each item of entries is a ListEntry:

entrystringRequired
Email address or domain (lowercased).
organization_idstringRequired
ID of the organization.
pod_idstring
ID of the pod, for pod-scoped entries.
inbox_idstring
ID of the inbox, for inbox-scoped entries.
reasonstring
Reason given when the entry was added.
direction"send" | "receive" | "reply"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.
list_type"allow" | "block"Required
block refuses matching addresses. allow makes the list exclusive: once it has an entry, only matching addresses pass.
entry_type"email" | "domain"Required
Whether the entry is an email address or a domain.
read_onlybooleanRequired
Always false: every entry can be deleted through the API.
created_atstring (date-time)Required
Time at which the entry was created.

Errors

StatusMeaning
400Invalid request: error.type is validation and error.param names the field.
401Missing, invalid, expired or revoked credential.
403The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account_suspended: error.message says what still works; do not retry or re-register).
404Not found. Also returned for resources outside the credential scope.
500Unexpected server error.

Error bodies use the error envelope.

Example

Request
curl "https://api.machinemail.dev/v0/lists/send/allow" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
Response 200
{
  "count": 1,
  "limit": 50,
  "next_page_token": "eyJvIjo1MH0",
  "entries": [
    {
      "entry": "customer@example.com",
      "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
      "pod_id": "pod_01k6x2m9qd0001b8j4mr0w3d5f",
      "inbox_id": "agent@machinemail.dev",
      "reason": "string",
      "direction": "send",
      "list_type": "allow",
      "entry_type": "email",
      "read_only": false,
      "created_at": "2026-10-01T12:00:00.000Z"
    }
  ]
}

Create List Entry

http
POST /v0/lists/{direction}/{type}

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 (the inbox has written to the sender) is the usual way to reach verified.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: list_entry_create.

Path parameters

direction"send" | "receive" | "reply"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.
type"allow" | "block"Required
block refuses matching addresses. allow makes the list exclusive: once it has an entry, only matching addresses pass.

Request body

Content type: application/json.

entrystringRequired
Email address or domain to add. (min length 1)
reasonstring
Reason for adding the entry.

Response

200 The entry (application/json)

entrystringRequired
Email address or domain (lowercased).
organization_idstringRequired
ID of the organization.
pod_idstring
ID of the pod, for pod-scoped entries.
inbox_idstring
ID of the inbox, for inbox-scoped entries.
reasonstring
Reason given when the entry was added.
direction"send" | "receive" | "reply"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.
list_type"allow" | "block"Required
block refuses matching addresses. allow makes the list exclusive: once it has an entry, only matching addresses pass.
entry_type"email" | "domain"Required
Whether the entry is an email address or a domain.
read_onlybooleanRequired
Always false: every entry can be deleted through the API.
created_atstring (date-time)Required
Time at which the entry was created.

Errors

StatusMeaning
400Invalid request: error.type is validation and error.param names the field.
401Missing, invalid, expired or revoked credential.
403The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account_suspended: error.message says what still works; do not retry or re-register).
404Not found. Also returned for resources outside the credential scope.
500Unexpected server error.

Error bodies use the error envelope.

Example

Request
curl -X POST "https://api.machinemail.dev/v0/lists/send/allow" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "entry": "customer@example.com",
  "reason": "string"
}'
Response 200
{
  "entry": "customer@example.com",
  "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
  "pod_id": "pod_01k6x2m9qd0001b8j4mr0w3d5f",
  "inbox_id": "agent@machinemail.dev",
  "reason": "string",
  "direction": "send",
  "list_type": "allow",
  "entry_type": "email",
  "read_only": false,
  "created_at": "2026-10-01T12:00:00.000Z"
}

Get List Entry

http
GET /v0/lists/{direction}/{type}/{entry}

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: list_entry_read.

Path parameters

direction"send" | "receive" | "reply"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.
type"allow" | "block"Required
block refuses matching addresses. allow makes the list exclusive: once it has an entry, only matching addresses pass.
entrystringRequired
Email address or domain.

Response

200 The entry (application/json)

entrystringRequired
Email address or domain (lowercased).
organization_idstringRequired
ID of the organization.
pod_idstring
ID of the pod, for pod-scoped entries.
inbox_idstring
ID of the inbox, for inbox-scoped entries.
reasonstring
Reason given when the entry was added.
direction"send" | "receive" | "reply"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.
list_type"allow" | "block"Required
block refuses matching addresses. allow makes the list exclusive: once it has an entry, only matching addresses pass.
entry_type"email" | "domain"Required
Whether the entry is an email address or a domain.
read_onlybooleanRequired
Always false: every entry can be deleted through the API.
created_atstring (date-time)Required
Time at which the entry was created.

Errors

StatusMeaning
401Missing, invalid, expired or revoked credential.
403The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account_suspended: error.message says what still works; do not retry or re-register).
404Not found. Also returned for resources outside the credential scope.
500Unexpected server error.

Error bodies use the error envelope.

Example

Request
curl "https://api.machinemail.dev/v0/lists/send/allow/customer@example.com" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
Response 200
{
  "entry": "customer@example.com",
  "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
  "pod_id": "pod_01k6x2m9qd0001b8j4mr0w3d5f",
  "inbox_id": "agent@machinemail.dev",
  "reason": "string",
  "direction": "send",
  "list_type": "allow",
  "entry_type": "email",
  "read_only": false,
  "created_at": "2026-10-01T12:00:00.000Z"
}

Delete List Entry

http
DELETE /v0/lists/{direction}/{type}/{entry}

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.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: list_entry_delete.

Path parameters

direction"send" | "receive" | "reply"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.
type"allow" | "block"Required
block refuses matching addresses. allow makes the list exclusive: once it has an entry, only matching addresses pass.
entrystringRequired
Email address or domain.

Response

200 Deleted (application/json)

oktrueRequired

Errors

StatusMeaning
401Missing, invalid, expired or revoked credential.
403The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account_suspended: error.message says what still works; do not retry or re-register).
404Not found. Also returned for resources outside the credential scope.
500Unexpected server error.

Error bodies use the error envelope.

Example

Request
curl -X DELETE "https://api.machinemail.dev/v0/lists/send/allow/customer@example.com" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
Response 200
{
  "ok": true
}

List Entries in Pod

http
GET /v0/pods/{pod_id}/lists/{direction}/{type}

Same as List Entries (GET /v0/lists/{direction}/{type}), limited to the pod. While any allow entry applies for a direction, every address that matches none is blocked (allow-only).

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: list_entry_read.

Path parameters

pod_idstringRequired
ID of the pod.
direction"send" | "receive" | "reply"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.
type"allow" | "block"Required
block refuses matching addresses. allow makes the list exclusive: once it has an entry, only matching addresses pass.

Query parameters

limitinteger
Maximum number of items to return. Default 50, maximum 500; larger values are capped.
page_tokenstring
next_page_token from the previous page.
ascendingboolean
false sorts by entry descending. Default true.

Response

200 A page of entries (application/json)

countintegerRequired
Number of items returned.
limitinteger
Maximum number of items per page. Default 50, maximum 500; larger values are capped.
next_page_tokenstring
Page token for pagination. Absent on the last page.
entriesListEntry[]Required
Ordered by entry, ascending unless ascending is false.

Each item of entries is a ListEntry:

entrystringRequired
Email address or domain (lowercased).
organization_idstringRequired
ID of the organization.
pod_idstring
ID of the pod, for pod-scoped entries.
inbox_idstring
ID of the inbox, for inbox-scoped entries.
reasonstring
Reason given when the entry was added.
direction"send" | "receive" | "reply"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.
list_type"allow" | "block"Required
block refuses matching addresses. allow makes the list exclusive: once it has an entry, only matching addresses pass.
entry_type"email" | "domain"Required
Whether the entry is an email address or a domain.
read_onlybooleanRequired
Always false: every entry can be deleted through the API.
created_atstring (date-time)Required
Time at which the entry was created.

Errors

StatusMeaning
400Invalid request: error.type is validation and error.param names the field.
401Missing, invalid, expired or revoked credential.
403The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account_suspended: error.message says what still works; do not retry or re-register).
404Not found. Also returned for resources outside the credential scope.
500Unexpected server error.

Error bodies use the error envelope.

Example

Request
curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/lists/send/allow" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
Response 200
{
  "count": 1,
  "limit": 50,
  "next_page_token": "eyJvIjo1MH0",
  "entries": [
    {
      "entry": "customer@example.com",
      "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
      "pod_id": "pod_01k6x2m9qd0001b8j4mr0w3d5f",
      "inbox_id": "agent@machinemail.dev",
      "reason": "string",
      "direction": "send",
      "list_type": "allow",
      "entry_type": "email",
      "read_only": false,
      "created_at": "2026-10-01T12:00:00.000Z"
    }
  ]
}

Create List Entry in Pod

http
POST /v0/pods/{pod_id}/lists/{direction}/{type}

Same as Create List Entry (POST /v0/lists/{direction}/{type}), limited to the pod. A receive/allow entry here makes this scope allow-only: mail from every sender that matches no allow entry is labeled BLOCKED and withheld from agents. An allow-listed sender reaches verified only with an aligned DMARC pass.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: list_entry_create.

Path parameters

pod_idstringRequired
ID of the pod.
direction"send" | "receive" | "reply"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.
type"allow" | "block"Required
block refuses matching addresses. allow makes the list exclusive: once it has an entry, only matching addresses pass.

Request body

Content type: application/json.

entrystringRequired
Email address or domain to add. (min length 1)
reasonstring
Reason for adding the entry.

Response

200 The entry (application/json)

entrystringRequired
Email address or domain (lowercased).
organization_idstringRequired
ID of the organization.
pod_idstring
ID of the pod, for pod-scoped entries.
inbox_idstring
ID of the inbox, for inbox-scoped entries.
reasonstring
Reason given when the entry was added.
direction"send" | "receive" | "reply"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.
list_type"allow" | "block"Required
block refuses matching addresses. allow makes the list exclusive: once it has an entry, only matching addresses pass.
entry_type"email" | "domain"Required
Whether the entry is an email address or a domain.
read_onlybooleanRequired
Always false: every entry can be deleted through the API.
created_atstring (date-time)Required
Time at which the entry was created.

Errors

StatusMeaning
400Invalid request: error.type is validation and error.param names the field.
401Missing, invalid, expired or revoked credential.
403The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account_suspended: error.message says what still works; do not retry or re-register).
404Not found. Also returned for resources outside the credential scope.
500Unexpected server error.

Error bodies use the error envelope.

Example

Request
curl -X POST "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/lists/send/allow" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "entry": "customer@example.com",
  "reason": "string"
}'
Response 200
{
  "entry": "customer@example.com",
  "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
  "pod_id": "pod_01k6x2m9qd0001b8j4mr0w3d5f",
  "inbox_id": "agent@machinemail.dev",
  "reason": "string",
  "direction": "send",
  "list_type": "allow",
  "entry_type": "email",
  "read_only": false,
  "created_at": "2026-10-01T12:00:00.000Z"
}

Get List Entry in Pod

http
GET /v0/pods/{pod_id}/lists/{direction}/{type}/{entry}

Same as Get List Entry (GET /v0/lists/{direction}/{type}/{entry}), limited to the pod.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: list_entry_read.

Path parameters

pod_idstringRequired
ID of the pod.
direction"send" | "receive" | "reply"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.
type"allow" | "block"Required
block refuses matching addresses. allow makes the list exclusive: once it has an entry, only matching addresses pass.
entrystringRequired
Email address or domain.

Response

200 The entry (application/json)

entrystringRequired
Email address or domain (lowercased).
organization_idstringRequired
ID of the organization.
pod_idstring
ID of the pod, for pod-scoped entries.
inbox_idstring
ID of the inbox, for inbox-scoped entries.
reasonstring
Reason given when the entry was added.
direction"send" | "receive" | "reply"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.
list_type"allow" | "block"Required
block refuses matching addresses. allow makes the list exclusive: once it has an entry, only matching addresses pass.
entry_type"email" | "domain"Required
Whether the entry is an email address or a domain.
read_onlybooleanRequired
Always false: every entry can be deleted through the API.
created_atstring (date-time)Required
Time at which the entry was created.

Errors

StatusMeaning
401Missing, invalid, expired or revoked credential.
403The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account_suspended: error.message says what still works; do not retry or re-register).
404Not found. Also returned for resources outside the credential scope.
500Unexpected server error.

Error bodies use the error envelope.

Example

Request
curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/lists/send/allow/customer@example.com" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
Response 200
{
  "entry": "customer@example.com",
  "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
  "pod_id": "pod_01k6x2m9qd0001b8j4mr0w3d5f",
  "inbox_id": "agent@machinemail.dev",
  "reason": "string",
  "direction": "send",
  "list_type": "allow",
  "entry_type": "email",
  "read_only": false,
  "created_at": "2026-10-01T12:00:00.000Z"
}

Delete List Entry in Pod

http
DELETE /v0/pods/{pod_id}/lists/{direction}/{type}/{entry}

Same as Delete List Entry (DELETE /v0/lists/{direction}/{type}/{entry}), limited to the pod.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: list_entry_delete.

Path parameters

pod_idstringRequired
ID of the pod.
direction"send" | "receive" | "reply"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.
type"allow" | "block"Required
block refuses matching addresses. allow makes the list exclusive: once it has an entry, only matching addresses pass.
entrystringRequired
Email address or domain.

Response

200 Deleted (application/json)

oktrueRequired

Errors

StatusMeaning
401Missing, invalid, expired or revoked credential.
403The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account_suspended: error.message says what still works; do not retry or re-register).
404Not found. Also returned for resources outside the credential scope.
500Unexpected server error.

Error bodies use the error envelope.

Example

Request
curl -X DELETE "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/lists/send/allow/customer@example.com" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
Response 200
{
  "ok": true
}

On this page

List Entries in InboxCreate List Entry in InboxGet List Entry in InboxDelete List Entry in InboxList EntriesCreate List EntryGet List EntryDelete List EntryList Entries in PodCreate List Entry in PodGet List Entry in PodDelete List Entry in Pod
0% read