Objects · MachineMail Docs

Skip to content Skip to content

[01/180]AgentIdentityRequest

Endpoint pages link here for nested objects. Fields marked required are always present in responses and must be sent in requests.

AgentIdentityRequest

FieldDescription

type``"anonymous" | "service_auth" | "identity_assertion"Required

Registration type.

name``string

Agent label (first 100 characters). Untrusted; shown as agent-described in the dashboard.

client_name``string

Alias of name.

login_hint``string

service_auth: email address of the user the agent acts for. Required for that type.

assertion_type``string

identity_assertion: urn:ietf:params:oauth:token-type:id-jag. Required for that type.

assertion``string

identity_assertion: the ID-JAG (signed JWT). Required for that type.

AgentIdentityResponse

FieldDescription

registration_id``stringRequired

agent_id``stringRequired

Same value as registration_id.

registration_type``"anonymous" | "service_auth" | "identity_assertion"Required

anonymous: no human yet; a sandbox inbox until a human claims it. service_auth: on behalf of a named user, who confirms first. identity_assertion: an ID-JAG from a trusted agent provider.

identity_assertion``string

Service-signed JWT to exchange at /oauth2/token. Absent for service_auth until the claim completes.

assertion_expires``string (date-time)

scopes``("inboxes.read" | "inboxes.write" | "messages.read" | "messages.send" | "messages.write" | "webhooks.read" | "webhooks.write" | "domains.read" | "domains.write" | "lists.read" | "lists.write" | "metrics.read" | "pods.read" | "pods.write" | "api_keys.read" | "api_keys.write")[]

identity_assertion registrations: the granted scopes.

pre_claim_scopes``("inboxes.read" | "inboxes.write" | "messages.read" | "messages.send" | "messages.write" | "webhooks.read" | "webhooks.write" | "domains.read" | "domains.write" | "lists.read" | "lists.write" | "metrics.read" | "pods.read" | "pods.write" | "api_keys.read" | "api_keys.write")[]

anonymous registrations: scopes before a human claims the agent (its sandbox inbox only).

post_claim_scopes``("inboxes.read" | "inboxes.write" | "messages.read" | "messages.send" | "messages.write" | "webhooks.read" | "webhooks.write" | "domains.read" | "domains.write" | "lists.read" | "lists.write" | "metrics.read" | "pods.read" | "pods.write" | "api_keys.read" | "api_keys.write")[]

Scopes after the claim.

claim_url``string

Where to start the claim ceremony (/agent/identity/claim).

claim_token``string

Secret for /agent/identity/claim and the claim grant.

claim_token_expires``string (date-time)

claim``object

service_auth registrations: the ceremony is already started.

inbox``object

anonymous registrations: the ephemeral sandbox inbox. There is no API key; authenticate with the access token from /oauth2/token.

AgentRegistration

An agent registration. Hashes and tokens are never included.

FieldDescription

agent_id``stringRequired

ID of the registration (reg_...).

registration_id``stringRequired

Same value as agent_id.

registration_type``"anonymous" | "service_auth" | "identity_assertion"Required

status``"pending_claim" | "claimed" | "revoked"Required

name``string

Agent-described label. Untrusted.

client``string

Provider name for identity_assertion, otherwise agent (self-described) or anonymous agent.

organization_id``string

Organization the registration is bound to (after a claim, or right away for identity_assertion).

inbox_id``string

The sandbox inbox of an anonymous registration.

email``string

Verified email bound at claim or carried by the identity assertion.

issuer``string

Issuer of the identity assertion (identity_assertion).

agent_platform``string

agent_platform claim of the identity assertion.

created_at``string (date-time)Required

When the agent registered.

claimed_at``string (date-time)

When a human claimed the registration.

revoked_at``string (date-time)

When the registration was revoked.

expires_at``string (date-time)

When an unclaimed registration expires.

ApiKeyPermissions

Permissions of the key, as { "<name>": true }. Only names set to true are granted; false is the same as leaving the name out. An omitted (or null) permission object means full access for the key scope, like {"*": true}; neither includes inbound_raw, which must be granted by name. A key can only be given permissions its creator has. Another name set to true (for example AgentMail’s calendar_*, app_* or account_update, which MachineMail does not support) is a 400.

FieldDescription

*``boolean

Every permission except inbound_raw. {"*": true, "inbound_raw": true} is full access plus raw injection.

inbox_read``boolean

Read inbox details.

inbox_create``boolean

Create new inboxes.

inbox_update``boolean

Update inbox settings.

inbox_delete``boolean

Delete inboxes.

thread_read``boolean

Read threads.

thread_delete``boolean

Delete threads.

message_read``boolean

Read messages.

message_reply``boolean

Reply and reply-all. message_send allows them too.

message_send``boolean

Send messages (and reply, reply-all, forward).

message_update``boolean

Update message labels. Also required to update threads.

message_delete``boolean

Delete messages.

label_spam_read``boolean

Access messages labeled spam.

label_blocked_read``boolean

Access messages labeled blocked.

label_unauthenticated_read``boolean

Access messages labeled unauthenticated.

label_trash_read``boolean

Access messages labeled trash.

draft_read``boolean

Read drafts.

draft_create``boolean

Create drafts.

draft_update``boolean

Update drafts.

draft_delete``boolean

Delete drafts.

draft_send``boolean

Send drafts.

webhook_read``boolean

Read webhook configurations.

webhook_create``boolean

Create webhooks.

webhook_update``boolean

Update webhooks.

webhook_delete``boolean

Delete webhooks.

domain_read``boolean

Read domain details.

domain_create``boolean

Create domains.

domain_update``boolean

Update domains.

domain_delete``boolean

Delete domains.

list_entry_read``boolean

Read list entries and suppressions.

list_entry_create``boolean

Create list entries and suppressions.

list_entry_delete``boolean

Delete list entries and suppressions.

trusted_domain_read``boolean

Read trusted domains and preview new ones.

trusted_domain_create``boolean

Add trusted domains. Organization API keys and the dashboard only: pod and inbox keys get 403 even with it.

trusted_domain_update``boolean

Change trusted domains. Organization API keys and the dashboard only, as for trusted_domain_create.

trusted_domain_delete``boolean

Remove trusted domains.

metrics_read``boolean

Read metrics and events.

api_key_read``boolean

Read API keys.

api_key_create``boolean

Create API keys.

api_key_update``boolean

Update API keys.

api_key_delete``boolean

Delete API keys.

pod_read``boolean

Read pods.

pod_create``boolean

Create pods.

pod_update``boolean

Update pods.

pod_delete``boolean

Delete pods.

inbound_raw``boolean

Inject raw mail with POST /inbound/raw. Never implied by an unrestricted key or *: it must be granted by name.

Attachment

FieldDescription

attachment_id``stringRequired

ID of the attachment.

filename``string

Filename of the attachment.

size``integerRequired

Size of the attachment in bytes.

content_type``string

Content type of the attachment.

content_disposition``string

Content disposition of the attachment (inline or attachment).

content_id``string

Content ID of the attachment.

AttachmentResponse

FieldDescription

attachment_id``stringRequired

ID of the attachment.

filename``string

Filename of the attachment.

size``integerRequired

Size of the attachment in bytes.

content_type``string

Content type of the attachment.

content_disposition``string

Content disposition of the attachment (inline or attachment).

content_id``string

Content ID of the attachment.

download_url``stringRequired

URL of the attachment bytes. Depending on the storage backend: a signed storage URL, the API URL GET .../attachments/{attachment_id}/download (send your API key), or a data: URI.

expires_at``string (date-time)Required

When download_url expires: one hour from the request unless the signed URL sets its own expiry.

AuthConfigResponse

How people sign in to MachineMail.

FieldDescription

workos``booleanRequired

Legacy alias of email_code, kept for older clients: sign in with an email code (POST /auth/email/start), a social provider (GET /auth/social/{provider}) or SSO.

email_code``booleanRequired

Email-code sign-in (POST /auth/email/start, then POST /auth/email/verify) is available.

providers``("google" | "github" | "apple" | "microsoft")[]Required

Social providers on offer (GET /auth/social/{provider}). Empty when none are offered.

magic_link``booleanRequired

Magic-link sign-in (POST /auth/magic-link) is available.

password``booleanRequired

The deprecated password endpoints are available.

authkit``booleanRequiredDeprecated

Deprecated: always false. Kept for older clients; see email_code.

passkey``booleanRequired

Passkey sign-in (POST /auth/passkey/options, then POST /auth/passkey/verify) is offered: show “Sign in with a passkey” and passkey autofill on the email field.

AuthorizationServerMetadata

RFC 8414 Authorization Server Metadata (as the MCP authorization specification asks for it) plus the auth.md agent_auth block.

FieldDescription

resource``stringRequired

The protected resource: / (the REST API and MCP), or / for a path-suffixed document. On the MCP server’s own host, the MCP server’s URL (https://mcp.machinemail.dev/mcp); on the issuer, /mcp is the legacy MCP alias.

authorization_servers``string[]Required

scopes_supported``("inboxes.read" | "inboxes.write" | "messages.read" | "messages.send" | "messages.write" | "webhooks.read" | "webhooks.write" | "domains.read" | "domains.write" | "lists.read" | "lists.write" | "metrics.read" | "pods.read" | "pods.write" | "api_keys.read" | "api_keys.write")[]Required

bearer_methods_supported``string[]Required

header.

issuer``stringRequired

authorization_endpoint``stringRequired

/oauth2/authorize: authorization code grant with PKCE (S256).

token_endpoint``stringRequired

registration_endpoint``stringRequired

/oauth2/register: Dynamic Client Registration (RFC 7591), public or confidential clients.

revocation_endpoint``stringRequired

device_authorization_endpoint``stringRequired

/auth/cli/device/code: the device grant of the MachineMail CLI (client_id machinemail-cli only).

jwks_uri``stringRequired

service_documentation``stringRequired

grant_types_supported``string[]Required

authorization_code, refresh_token, urn:ietf:params:oauth:grant-type:device_code, urn:ietf:params:oauth:grant-type:jwt-bearer, urn:workos:agent-auth:grant-type:claim.

response_types_supported``string[]Required

code.

response_modes_supported``string[]Required

query.

code_challenge_methods_supported``string[]Required

S256.

token_endpoint_auth_methods_supported``string[]Required

none (public clients: every URL client ID, and registrations without a secret), client_secret_post and client_secret_basic (registrations that asked for a secret). Every client uses PKCE.

revocation_endpoint_auth_methods_supported``string[]Required

Same as token_endpoint_auth_methods_supported.

client_id_metadata_document_supported``booleanRequired

true: an https URL is accepted as client_id (OAuth Client ID Metadata Document).

authorization_response_iss_parameter_supported``booleanRequired

true: authorization responses carry iss (RFC 9207).

agent_auth``objectRequired

BatchGetMessagesRequest

FieldDescription

message_ids``string[]Required

IDs of the messages to fetch. Only the first 100 distinct IDs are read.

BatchGetMessagesResponse

FieldDescription

limit``integerRequired

Number of IDs in the request.

count``integerRequired

Number of messages returned.

messages Message[] Required

Found messages, in request order. IDs not found in the inbox are omitted.

BatchUpdateMessagesRequest

FieldDescription

message_ids``string[]Required

IDs of the messages to update. Only the first 100 distinct IDs are updated.

add_labels``string | string[]

Label or labels to add to every message.

remove_labels``string | string[]

Label or labels to remove from every message.

BatchUpdateMessagesResponse

FieldDescription

limit``integerRequired

Number of IDs in the request.

count``integerRequired

Number of messages updated.

updates UpdateMessageResponse[] Required

Updated messages with their new labels, in request order. IDs not found are omitted.

BearerApiKey

An API key presented as a bearer token in the Authorization header.

FieldDescription

type``"bearer"Required

Always bearer: MachineMail has no public-key credentials.

api_key_id``stringRequired

ID of the API key.

prefix``stringRequired

First 12 characters of the key (mm_live_ and 4 more), safe to display.

name``stringRequired

Name of the key.

pod_id``string

Pod the key is scoped to: it can only access resources in this pod.

inbox_id``string

Inbox the key is scoped to: it can only access this inbox.

permissions ApiKeyPermissions

Permissions of the key, as { "": true }. Only names set to true are granted; false is the same as leaving the name out. An omitted (or null) permission object means full access for the key scope, like {"*": true}; neither includes inbound_raw, which must be granted by name. A key can only be given permissions its creator has. Another name set to true (for example AgentMail’s calendar_*, app_* or account_update, which MachineMail does not support) is a 400.

created_at``string (date-time)Required

Time at which the key was created.

expires_at``string (date-time)

Time at which the key expires: requests with it then get 401. Absent when it does not expire.

organization_id``stringRequired

ID of the organization.

used_at``string (date-time)

Time at which the key was last used.

revoked_at``string (date-time)

When the key was deleted (revoked). Revoked keys are not listed but can still be fetched by ID.

updated_at``string (date-time)Required

Time at which the name, permissions or revocation last changed. Use does not change it.

Bounce

FieldDescription

inbox_id``stringRequired

ID of the inbox.

thread_id``stringRequired

ID of the thread.

message_id``stringRequired

ID of the message.

timestamp``string (date-time)Required

When it happened.

type``stringRequired

Bounce type: Permanent or Transient (or the provider type).

sub_type``stringRequired

Bounce sub-type, General when the provider gives none.

recipients Recipient[] Required

Bounced recipients. Permanent bounces are added to the suppression list.

ClaimBlock

RFC 8628-shaped claim ceremony block.

FieldDescription

user_code``stringRequired

6-digit code the human enters in the dashboard.

verification_uri``stringRequired

https://machinemail.dev/claim?claim\_attempt\_token=cat\_...: the page to send the human to.

expires_in``integerRequired

Seconds until user_code expires.

interval``integerRequired

Minimum seconds between /oauth2/token polls.

ClaimCompleteRequest

FieldDescription

user_code``stringRequired

The 6-digit code the agent shows; spaces and dashes are ignored.

claim_attempt_token``string

The cat_... token from verification_uri; when given, it must belong to the same attempt as user_code.

ClaimCompleteResponse

The claimed registration plus the moved inbox.

FieldDescription

agent_id``stringRequired

ID of the registration (reg_...).

registration_id``stringRequired

Same value as agent_id.

registration_type``"anonymous" | "service_auth" | "identity_assertion"Required

status``"claimed"Required

name``string

Agent-described label. Untrusted.

client``string

Provider name for identity_assertion, otherwise agent (self-described) or anonymous agent.

organization_id``stringRequired

The organization of the signed-in user.

inbox_id``string

The sandbox inbox of an anonymous registration.

email``string

Verified email bound at claim or carried by the identity assertion.

issuer``string

Issuer of the identity assertion (identity_assertion).

agent_platform``string

agent_platform claim of the identity assertion.

created_at``string (date-time)Required

When the agent registered.

claimed_at``string (date-time)

When a human claimed the registration.

revoked_at``string (date-time)

When the registration was revoked.

expires_at``string (date-time)

When an unclaimed registration expires.

inbox``object

The former sandbox inbox, now permanent and in the user’s default pod.

ClaimPreviewResponse

An agent registration plus the claim details.

FieldDescription

agent_id``stringRequired

ID of the registration (reg_...).

registration_id``stringRequired

Same value as agent_id.

registration_type``"anonymous" | "service_auth" | "identity_assertion"Required

status``"pending_claim" | "claimed" | "revoked"Required

name``string

Agent-described label. Untrusted.

client``string

Provider name for identity_assertion, otherwise agent (self-described) or anonymous agent.

organization_id``string

Organization the registration is bound to (after a claim, or right away for identity_assertion).

inbox_id``string

The sandbox inbox of an anonymous registration.

email``string

Verified email bound at claim or carried by the identity assertion.

issuer``string

Issuer of the identity assertion (identity_assertion).

agent_platform``string

agent_platform claim of the identity assertion.

created_at``string (date-time)Required

When the agent registered.

claimed_at``string (date-time)

When a human claimed the registration.

revoked_at``string (date-time)

When the registration was revoked.

expires_at``string (date-time)

When an unclaimed registration expires.

claim_email``string

Only this user may claim the registration.

user_code_expires_at``string (date-time)

When the code expires.

sandbox_inbox``object

The sandbox inbox of an anonymous registration.

ClaimStartRequest

Send claim_token (and optionally email), or agent_id with Bearer proof.

FieldDescription

claim_token``string

Protocol form: the claim_token from registration.

email``string

Binds the claim to this human. For service_auth and identity_assertion it must match the bound email.

agent_id``string

Alternative to claim_token; needs the registration’s access token or identity assertion as Authorization: Bearer.

registration_id``string

Alias of agent_id.

ClaimStartResponse

The claim_attempt block and the flat user_code, verification_uri, expires_in and interval carry the same values.

FieldDescription

registration_id``stringRequired

agent_id``stringRequired

claim_attempt_id``stringRequired

status``"initiated"Required

expires_at``string (date-time)Required

When this attempt expires.

claim_attempt ClaimBlock Required

RFC 8628-shaped claim ceremony block.

user_code``stringRequired

6-digit code the human enters in the dashboard.

verification_uri``stringRequired

https://machinemail.dev/claim?claim\_attempt\_token=cat\_...: the page to send the human to.

expires_in``integerRequired

Seconds until user_code expires.

interval``integerRequired

Minimum seconds between /oauth2/token polls.

CliDeviceApproveRequest

FieldDescription

user_code``stringRequired

The code the CLI printed (XXXX-XXXX); case, spaces and dashes are ignored.

organization_id``string

The organization the key is for, as the page showed it: it must be the one the session is signed in to (409 conflict otherwise, for example after another tab switched organizations). To create the key in another organization the person belongs to, switch the session to it first (POST /auth/organizations/switch). Default: the session’s organization.

CliDeviceAuthorization

A pending CLI sign-in, as the approval page shows it. Never includes the device code.

FieldDescription

user_code``stringRequired

The code, formatted XXXX-XXXX.

device_id``stringRequired

Opaque ID of this sign-in (cld_...), not a secret: the device_id of the session.cli.device stream events that report it approved, denied or redeemed.

client_id``stringRequired

Always machinemail-cli.

client_name``string | nullRequired

What the CLI says it is. Self-reported.

hostname``string | nullRequired

The machine the CLI says it runs on. Self-reported.

key_name``stringRequired

Name of the key approval creates: CLI on .

permissions``string[]Required

Permissions of that key: ["*"] (every permission except inbound_raw).

created_at``string (date-time)Required

When the CLI asked for the code.

expires_at``string (date-time)Required

When the code expires.

CliDeviceCodeRequest

FieldDescription

client_id``stringRequired

Always machinemail-cli.

client_name``string

Shown to the human on the approval page, for example MachineMail CLI 0.4.0. At most 100 characters. (max length 100)

hostname``string

The machine the CLI runs on. Names the key (CLI on ) and is shown on the approval page. At most 253 characters. (max length 253)

CliDeviceCodeResponse

RFC 8628 device authorization response.

FieldDescription

device_code``stringRequired

Secret the CLI polls the token endpoint with. Never show it.

user_code``stringRequired

Code the human checks on the approval page: 8 letters as XXXX-XXXX (consonants only, no look-alikes).

verification_uri``stringRequired

https://machinemail.dev/cli: where the human approves.

verification_uri_complete``stringRequired

verification_uri with ?code=<user_code>, for opening in a browser.

expires_in``integerRequired

Seconds until both codes expire (600).

interval``integerRequired

Minimum seconds between polls of the token endpoint (5).

CliDeviceDecision

FieldDescription

status``"approved" | "denied"Required

key_name``stringRequired

Name of the key the CLI receives (approved) or would have received (denied).

CliDeviceDecisionRequest

FieldDescription

user_code``stringRequired

The code the CLI printed (XXXX-XXXX); case, spaces and dashes are ignored.

CliDeviceTokenRequest

FieldDescription

grant_type``stringRequired

urn:ietf:params:oauth:grant-type:device_code.

device_code``stringRequired

The device_code from the device authorization response.

client_id``stringRequired

Always machinemail-cli.

CliDeviceTokenResponse

An organization API key with every permission except inbound_raw, minted for the approving user.

FieldDescription

access_token``stringRequired

The new API key (mm_live_...). Returned once; send it as Authorization: Bearer.

token_type``"Bearer"Required

api_key_id``stringRequired

ID of the key, for DELETE /v0/api-keys/{api_key_id} on logout.

key_name``stringRequired

Name of the key: CLI on .

organization Organization Required

The organization the key belongs to.

user User Required

The person who approved the sign-in.

ClientRegistrationRequest

RFC 7591 client metadata. Unknown members are ignored.

FieldDescription

redirect_uris``string[]Required

Where the authorization response may be sent: https URLs, http loopback URLs (http://127.0.0.1, http://[::1] or http://localhost; any port is accepted at authorization time, RFC 8252), or a private-use scheme of a native app (cursor://...). No fragments. At most 10. (min items 1, max items 10)

client_name``string

Shown on the consent page, marked as unverified. At most 200 characters. (max length 200)

client_uri``string

Home page of the client; shown on the consent page when it is https. (max length 2000)

logo_uri``string

Logo shown on the consent page when it is https. (max length 2000)

token_endpoint_auth_method``string

none (the default: a public client, PKCE only), client_secret_post or client_secret_basic (a confidential client: the response carries a client_secret, and the token endpoint accepts it either way). Any other value is replaced with none in the response (RFC 7591 section 3.2.1).

grant_types``string[]

authorization_code and refresh_token (the default). Must include authorization_code (invalid_client_metadata otherwise); other values are dropped from the registration.

response_types``string[]

code (the default). Other values: invalid_client_metadata.

scope``string

Space-separated Scope values the client may ask for. Default: every scope. (max length 2000)

application_type``"native" | "web"

native or web (OpenID Connect Dynamic Client Registration; required by MCP 2026-07-28). Default web.

software_id``string

Identifier of the client software. Stored, not verified. (max length 200)

software_version``string

Version of the client software. Stored, not verified. (max length 100)

ClientRegistrationResponse

RFC 7591 client information response. A public client has no client_secret.

FieldDescription

client_id``stringRequired

The new client identifier (oac_...).

client_id_issued_at``integerRequired

Seconds since the epoch.

client_name``string

client_uri``string

logo_uri``string

redirect_uris``string[]Required

grant_types``string[]Required

response_types``string[]Required

token_endpoint_auth_method``"none" | "client_secret_post" | "client_secret_basic"Required

As requested when supported, otherwise none.

client_secret``string

Confidential clients only (client_secret_post, client_secret_basic): shown once, stored only as a hash. Keep it secret.

client_secret_expires_at``integer

With client_secret: 0, the secret does not expire.

application_type``"native" | "web"Required

scope``string

software_id``string

software_version``string

Complaint

FieldDescription

inbox_id``stringRequired

ID of the inbox.

thread_id``stringRequired

ID of the thread.

message_id``stringRequired

ID of the message.

timestamp``string (date-time)Required

When it happened.

type``stringRequired

Complaint type, complaint when the provider gives none.

sub_type``stringRequired

Complaint sub-type, abuse when the provider gives none.

recipients Recipient[] Required

Complaining recipients, as {address, status} objects (AgentMail documents plain strings). They are added to the suppression list.

CreateApiKeyResponse

FieldDescription

api_key_id``stringRequired

ID of the API key.

prefix``stringRequired

First 12 characters of the key (mm_live_ and 4 more), safe to display.

name``stringRequired

Name of the key.

pod_id``string

Pod the key is scoped to: it can only access resources in this pod.

inbox_id``string

Inbox the key is scoped to: it can only access this inbox.

permissions ApiKeyPermissions

created_at``string (date-time)Required

Time at which the key was created.

expires_at``string (date-time)

Time at which the key expires: requests with it then get 401. Absent when it does not expire.

api_key``stringRequired

The key itself (mm_live_ and 32 characters). Returned once; only a hash is stored.

CreateBearerApiKeyRequest

The route sets the scope: /v0/api-keys makes an organization key, /v0/pods/{pod_id}/api-keys a pod key, /v0/inboxes/{inbox_id}/api-keys an inbox key.

FieldDescription

name``string

Name of the key. Default API key.

permissions``object | null

Permissions of the new key. Omitted or null: full access for the key scope (inbound_raw excepted).

expires_at``string (date-time) | null

When the key stops working, as an RFC 3339 timestamp at least 5 minutes from now (400 otherwise). A date alone or a time without a zone is read as UTC. Omit it or send null for no expiry (a key created with an expiring API key gets that key’s expiry instead). A key created with another API key cannot outlive it: a later time is a 403. An inherited expiry can be under 5 minutes away. It cannot be changed later; create a new key instead.

CreateDomainRequest

FieldDescription

domain``stringRequired

The domain name, for example example.com. Cannot be the shared domain or a domain another organization registered.

feedback_enabled``boolean

Stored and returned; has no effect. Default false.

inbound_enabled``boolean

Receive email for this domain. Default true. false makes it send-only (the inbound MX record is not required).

client_id``string

Idempotency key: a create with a client_id already used in the organization returns that domain with 200, or 409 when that domain is outside the pod of the API key or route.

pod_id``string

Pod to create the domain in. Defaults to the credential pod or the organization default pod. A pod-scoped credential can only name its own pod.

catch_all``boolean

Create an inbox for any address at the domain that receives mail. Default false.

catch_all_ttl_seconds``integer | null

Make inboxes created by catch-all ephemeral with this TTL. null or absent: permanent.

CreateDraftRequest

FieldDescription

labels``string[]

Labels of the draft.

reply_to``string | string[]

Reply-to addresses: one address or a list.

to``string | string[]

Recipient addresses: one address or a list.

cc``string | string[]

CC addresses: one address or a list.

bcc``string | string[]

BCC addresses: one address or a list.

subject``string

Subject.

text``string

Plain text body.

html``string

HTML body.

attachments SendAttachment[]

Attachments, sent with the draft. Each needs content or url; a url is fetched when the draft is sent.

in_reply_to``string

ID of a message in this inbox to reply to: the sent message gets its In-Reply-To and References headers.

send_at``string (date-time) | null

Schedule the draft: it is sent automatically at this time (send_status: scheduled). null or absent: not scheduled.

client_id``string

Idempotency key: a create with a client_id already used in the organization returns that draft with 200, or 409 when that draft is outside the pod or inbox of the API key or route.

CreatedTrustedDomain

The entry, with any warnings about mail that stays blocked.

FieldDescription

trusted_domain_id``stringRequired

ID of the entry (td_...).

entry_type``"domain" | "email"Required

domain: every address at the domain (and its subdomains with include_subdomains). email: exactly one address.

domain``stringRequired

The domain, or for entry_type: "email" the address, lowercased, with the domain in its ASCII (punycode) form.

domain_unicode``stringRequired

The same, with the domain in its Unicode form. Equal to domain for ASCII names.

include_subdomains``booleanRequired

Also trust mail signed by subdomains (billing.example.com for example.com). Always false for addresses.

scope``"org" | "pod" | "inbox"Required

Where an entry applies: the whole organization, one pod, or one inbox.

pod_id``string | nullRequired

The pod, for pod- and inbox-scoped entries.

inbox_id``string | nullRequired

The inbox, for inbox-scoped entries.

reason``string | nullRequired

Why it was added, for people reading the list. Never included in a message’s trust report.

expires_at``string (date-time) | nullRequired

When the entry stops applying. null: never.

created_by``object | nullRequired

Who added the entry.

match_count``integerRequired

Messages this entry has marked trusted.

last_matched_at``string (date-time) | nullRequired

When this entry last marked a message trusted. null: never.

created_at``string (date-time)Required

When the entry was added.

updated_at``string (date-time)Required

When the entry last changed.

warnings Warning[] Required

Conflicts with block entries or allow-only scopes. Empty when there are none.

CreateInboxRequest

FieldDescription

username``string

Local part of the address: a-z, 0-9 and . _ + -, 1 to 64 characters. Randomly generated if omitted. On the shared domain, a username equal to another organization's slug is reserved for that organization (409).

domain``string

Domain of the address: a domain verified by this organization. Defaults to the shared domain.

display_name``string

Display name: Display Name username@domain.com.

client_id``string

Idempotency key: a create with a client_id already used in the organization returns that inbox with 200, or 409 when that inbox is outside the pod of the API key or route.

status``"active" | "paused"

Whether the inbox sends and receives mail. paused stops both: sends return 403 (Inbox <inbox_id> is paused), and incoming mail is not stored; a message.rejected event with reason inbox_paused is emitted instead. Mail already in the inbox, its drafts and its API keys are kept. Set active to resume.

metadata``Record<string, string | number | boolean>

Custom key-value pairs attached to the inbox.

pod_id``string

Pod to create the inbox in. Defaults to the credential pod or the organization default pod.

ephemeral``boolean

true without ttl_seconds creates an ephemeral inbox with a one hour TTL (3600 seconds).

ttl_seconds``integer | null

Creates an ephemeral inbox that expires ttl_seconds after creation, extended by each inbound message.

import_source``"agentmail"

Marks an inbox copied from another provider by an importer (machinemail import agentmail sets agentmail). The only effect: its inbox.created event is not delivered to webhooks or MCP subscribers, so they are not notified about an inbox that already existed elsewhere. The event is still recorded (GET /v0/events, the event stream), marked as an import in its payload, so the event log shows every import. Everything else about the create is unchanged.

CreateInvitationRequest

FieldDescription

email``stringRequired

Address to invite.

role``"owner" | "admin" | "member"

Role on joining. Default member. Only owners can invite owners.

CreateListEntryRequest

FieldDescription

entry``stringRequired

Email address or domain to add. (min length 1)

reason``string

Reason for adding the entry.

CreatePodRequest

FieldDescription

name``string

Name of the pod. Default Untitled pod.

client_id``string

Idempotency key: a create with a client_id already used in the organization returns that pod with 200.

CreateSessionOrganizationRequest

FieldDescription

name``stringRequired

Name of the new organization.

CreateSuppressionRequest

FieldDescription

email``stringRequired

Address to suppress.

detail``string

Note stored as detail.

reason``stringDeprecated

Old name of detail (it is stored as detail; the suppression reason is always manual). Ignored when detail is set.

CreateTrustedDomainRequest

FieldDescription

domain``stringRequired

A domain (example.com) or an exact address (invoices@example.com). Unicode names are accepted and stored in ASCII (punycode) form. (min length 1, max length 320)

include_subdomains``boolean

Also trust mail signed by subdomains. Default false. Not allowed for an address.

reason``string

Why you trust it, for people reading the list. Never included in a message’s trust report. (max length 500)

expires_at``string (date-time)

When the entry stops applying. Must be in the future. Omit for never.

confirm``boolean

Required (true) for platforms where anyone can write the content (github.com, google.com, slack.com and similar, or one under the domain with include_subdomains) and for one address on a group or marketplace relay (team@googlegroups.com): without it the answer is 422 confirmation_required.

client_id``string

Idempotency key: a create with a client_id already used in the organization returns that entry (200).

CreateWebhookRequest

FieldDescription

url``stringRequired

Endpoint URL: a public http(s) URL (private and loopback addresses are rejected, and re-checked before every delivery).

event_types``("message.received" | "message.received.spam" | "message.received.quarantined" | "message.received.unauthenticated" | "message.received.blocked" | "message.sent" | "message.delivered" | "message.bounced" | "message.complained" | "message.rejected" | "domain.verified" | "domain.updated" | "inbox.created" | "inbox.expired" | "draft.sent" | "webhook.test" | "trusted_domain.created" | "trusted_domain.updated" | "trusted_domain.deleted")[]

Event types the webhook receives. Omit it or send an empty array to receive every event type except domain.updated and trusted_domain.*, which are sent only when listed.

client_id``string

Idempotency key: a create with a client_id already used in the organization returns that webhook with 200, or 409 when that webhook is outside the pod or inbox of the API key or route.

inbox_ids``string[]

Only deliver events of these inboxes.

pod_ids``string[]

Only deliver events of these pods.

headers``Record<string, string>

Custom HTTP headers sent with every delivery to this webhook (every attempt, retry, replay and test event), alongside the X-MachineMail-* headers, for example {"Authorization": "Bearer "} for an endpoint that requires one. Values are write-only: they are stored encrypted and no response returns them; reads list the names (header_names). The headers are not part of the signed payload: X-MachineMail-Signature covers the body only. At most 10 headers. Names are HTTP tokens of up to 64 characters, compared without regard to case; values are printable ASCII (no line breaks or control characters) of up to 4096 characters, with surrounding spaces removed, and names plus values total at most 8192 bytes. Reserved names are refused with 400: Host, Content-Length, Content-Type, Content-Encoding, Transfer-Encoding, Connection, Upgrade, TE, Trailer, Keep-Alive, Expect, User-Agent, Accept-Encoding, and every name starting with Proxy-, Sec-, X-MachineMail-, Svix- or Webhook-. Authorization and Cookie are allowed.

DeleteOrganizationRequest

FieldDescription

code``stringRequired

The 6-digit code from the email.

DeleteOrganizationResponse

The organization is deleted.

FieldDescription

ok``trueRequired

organization_id``stringRequired

ID of the deleted organization.

Delivery

FieldDescription

inbox_id``stringRequired

ID of the inbox.

thread_id``stringRequired

ID of the thread.

message_id``stringRequired

ID of the message.

timestamp``string (date-time)Required

When it happened.

recipients``string[]Required

Delivered recipients.

Domain

FieldDescription

pod_id``stringRequired

ID of the pod the domain belongs to.

domain_id``stringRequired

ID of the domain.

domain``stringRequired

The domain name (for example example.com), lowercased.

feedback_enabled``booleanRequired

Stored as given. MachineMail does not send bounce and complaint notifications to inboxes; use the message.bounced and message.complained events.

inbound_enabled``booleanRequired

Receive email for this domain. false makes it send-only: the inbound MX record is not required.

subdomains_enabled``booleanRequired

Always false: inboxes on subdomains are not supported.

tracking_enabled``booleanRequired

Always false: open tracking is not supported.

client_id``string

Client ID given at creation (idempotency key).

updated_at``string (date-time)Required

Time at which the domain was last updated.

created_at``string (date-time)Required

Time at which the domain was created.

status``"NOT_STARTED" | "PENDING" | "INVALID" | "FAILED" | "VERIFYING" | "VERIFIED"Required

NOT_STARTED until the first verify, then VERIFIED when every required record is valid, INVALID when a required record has the wrong value, otherwise PENDING. For domains whose email provider reports its own verdict (Amazon SES): VERIFYING while every required record checks out but the provider has not confirmed them yet, and FAILED when the provider gave up (reason says why).

reason``string

Why the domain is not verified yet: what to do next, or which records are missing or invalid. Absent once VERIFIED.

records VerificationRecord[] Required

DNS records to publish.

organization_id``stringRequired

ID of the organization.

catch_all``booleanRequired

Mail to any address at the domain without an inbox creates one (created_by: catch_all).

catch_all_ttl_seconds``integer

TTL of inboxes created by catch-all; absent means they are permanent.

nameservers``string[]

Authoritative nameservers, detected on create and verify.

dns_provider``"cloudflare" | "route53" | "google" | "vercel" | "namecheap" | "godaddy" | "digitalocean" | "hetzner" | "porkbun" | "other"

DNS host the nameservers belong to.

dns_provider_url``string

Link to the DNS host console.

domain_connect``object

One-click DNS setup (Domain Connect), from the last discovery. See Get Domain Connect Setup.

verified_at``string (date-time)

When the domain became VERIFIED.

last_checked_at``string (date-time)

When the DNS records were last checked.

DomainConnect

FieldDescription

supported``booleanRequired

The zone DNS provider supports Domain Connect and has the MachineMail template.

provider_name``string

Display name of the DNS provider.

apply_url``string

Signed link that opens the provider with the outstanding records prefilled. Absent when nothing is left to add.

provider_id``string

Domain Connect provider ID.

url_sync_ux``string

Base URL of the provider synchronous flow.

width``integer

Suggested popup width, in pixels.

height``integer

Suggested popup height, in pixels.

reason``"no_domain_connect" | "provider_error" | "no_sync_flow" | "template_not_supported" | "records_not_templatable" | "already_configured" | "not_configured"

Why one-click setup is not available, or already_configured when nothing is left to add.

checked_at``string (date-time)Required

When discovery last ran.

DomainItem

FieldDescription

pod_id``stringRequired

ID of the pod the domain belongs to.

domain_id``stringRequired

ID of the domain.

domain``stringRequired

The domain name (for example example.com), lowercased.

feedback_enabled``booleanRequired

Stored as given. MachineMail does not send bounce and complaint notifications to inboxes; use the message.bounced and message.complained events.

inbound_enabled``booleanRequired

Receive email for this domain. false makes it send-only: the inbound MX record is not required.

subdomains_enabled``booleanRequired

Always false: inboxes on subdomains are not supported.

tracking_enabled``booleanRequired

Always false: open tracking is not supported.

client_id``string

Client ID given at creation (idempotency key).

updated_at``string (date-time)Required

Time at which the domain was last updated.

created_at``string (date-time)Required

Time at which the domain was created.

status``"NOT_STARTED" | "PENDING" | "INVALID" | "FAILED" | "VERIFYING" | "VERIFIED"Required

Verification status, as on Domain.

reason``string

Why the domain is not verified yet, as on Domain.

records VerificationRecord[] Required

DNS records to publish, as on Domain.

organization_id``stringRequired

ID of the organization.

catch_all``booleanRequired

Mail to any address at the domain without an inbox creates one (created_by: catch_all).

catch_all_ttl_seconds``integer

TTL of inboxes created by catch-all; absent means they are permanent.

nameservers``string[]

Authoritative nameservers, detected on create and verify.

dns_provider``"cloudflare" | "route53" | "google" | "vercel" | "namecheap" | "godaddy" | "digitalocean" | "hetzner" | "porkbun" | "other"

DNS host the nameservers belong to.

dns_provider_url``string

Link to the DNS host console.

domain_connect``object

One-click DNS setup (Domain Connect), from the last discovery. See Get Domain Connect Setup.

verified_at``string (date-time)

When the domain became VERIFIED.

last_checked_at``string (date-time)

When the DNS records were last checked.

Draft

FieldDescription

inbox_id``stringRequired

ID of the inbox.

draft_id``stringRequired

ID of the draft.

labels``string[]Required

Labels of the draft. The sent message gets them.

to``string[]

Recipient addresses.

cc``string[]

CC addresses.

bcc``string[]

BCC addresses.

subject``string

Subject of the draft.

preview``string

Text preview of the draft.

attachments Attachment[]

Attachments of the draft. size is 0 for attachments given by url until the draft is sent (the URL is fetched then).

in_reply_to``string

ID of the message being replied to.

send_status``"scheduled" | "sending" | "failed"

scheduled while waiting for send_at, sending while a sender holds it, failed when a scheduled send failed (it is not retried). Absent on drafts without send_at.

send_at``string (date-time)

Time at which the draft is sent automatically.

updated_at``string (date-time)Required

Time at which the draft was last updated.

client_id``string

Client ID given at creation (idempotency key).

reply_to``string[]

Reply-to addresses.

text``string

Plain text body.

html``string

HTML body.

references``string[]

Message IDs the draft references (set from in_reply_to).

created_at``string (date-time)Required

Time at which the draft was created.

pod_id``stringRequired

ID of the pod.

DraftItem

FieldDescription

inbox_id``stringRequired

ID of the inbox.

draft_id``stringRequired

ID of the draft.

labels``string[]Required

Labels of the draft. The sent message gets them.

to``string[]

Recipient addresses.

cc``string[]

CC addresses.

bcc``string[]

BCC addresses.

subject``string

Subject of the draft.

preview``string

Text preview of the draft.

attachments Attachment[]

Attachments of the draft. size is 0 for attachments given by url until the draft is sent (the URL is fetched then).

in_reply_to``string

ID of the message being replied to.

send_status``"scheduled" | "sending" | "failed"

send_at``string (date-time)

Time at which the draft is sent automatically.

updated_at``string (date-time)Required

Time at which the draft was last updated.

client_id``string

Client ID given at creation.

reply_to``string[]

Reply-to addresses.

text``string

Plain text body.

html``string

HTML body.

references``string[]

Message IDs the draft references.

created_at``string (date-time)Required

Time at which the draft was created.

pod_id``stringRequired

ID of the pod.

EmailCodesRequest

FieldDescription

enabled``booleanRequired

false turns email sign-in codes off; true back on.

EmailCodesResponse

FieldDescription

email_codes``booleanRequired

Email sign-in codes work for this account now.

EmailCodeStartRequest

FieldDescription

email``string

Address to send the code to. Optional with invitation_token (the code goes to the invited address).

next``string

Same-origin path to land on after sign-in, for example /cli?code=ABCD-EFGH. Anything else is ignored. Default /app.

invitation_token``string

An invitation token (from /invite/{token}): signing in accepts the invitation.

EmailCodeStartResponse

FieldDescription

ok``trueRequired

redirect_to``string

Set when the address’s domain signs in with SSO: send the browser here (the organization’s identity provider). Otherwise a code was emailed: show the code screen.

EmailCodeVerifyRequest

FieldDescription

code``stringRequired

The 6-digit code from the email. Spaces and dashes are ignored.

Event

An event in the replayable log. Webhooks, the SSE stream and the WebSocket deliver the event envelope instead (type: "event" with the data keys also at the top level).

FieldDescription

event_id``stringRequired

ID of the event (evt_...). Sorts by creation time.

event_type``"message.received" | "message.received.spam" | "message.received.quarantined" | "message.received.unauthenticated" | "message.received.blocked" | "message.sent" | "message.delivered" | "message.bounced" | "message.complained" | "message.rejected" | "domain.verified" | "domain.updated" | "inbox.created" | "inbox.expired" | "draft.sent" | "webhook.test" | "trusted_domain.created" | "trusted_domain.updated" | "trusted_domain.deleted" | "registration.created" | "token.issued" | "agent.claimed" | "agent.revoked" | "member.invited" | "member.role_changed" | "member.removed"Required

Type of event: an events_EventType, or an audit event for agent registrations and members (registration.created, token.issued, agent.claimed, agent.revoked, member.invited, member.role_changed, member.removed), which is logged but never delivered to webhooks or streams.

organization_id``stringRequired

ID of the organization.

pod_id``string

ID of the pod. Absent for organization-level events.

inbox_id``string

ID of the inbox. Absent for events without an inbox (for example domain.verified).

data``Record<string, unknown>Required

Event payload, as delivered to webhooks: message.* events carry message and thread, delivery events their send, delivery, bounce, complaint or reject object, inbox.* the inbox, domain.verified and domain.updated the domain, trusted_domain.* the trusted_domain.

timestamp``string (date-time)Required

When the event happened (same as created_at).

created_at``string (date-time)Required

When the event was stored.

FirstKeyResponse

FieldDescription

api_key OneTimeApiKey Required

An API key with its plaintext secret, returned once.

HealthResponse

FieldDescription

status``"ok"Required

Identity

Identity and scope of the credential.

FieldDescription

scope_type``"organization" | "pod" | "inbox"Required

The scope tier the credential is bound to.

scope_id``stringRequired

ID of the most specific scope: inbox_id for an inbox credential, pod_id for a pod credential, otherwise organization_id.

organization_id``stringRequired

ID of the organization.

pod_id``string

ID of the pod the credential is scoped to. Present when scope_type is pod, and for inbox credentials created under a pod.

inbox_id``string

ID of the inbox the credential is scoped to. Present when scope_type is inbox.

api_key_id``string

ID of the API key used. Absent for dashboard sessions and agent access tokens.

api_key_expires_at``string (date-time)

When the API key used expires. Absent when it does not expire, and for other credentials.

user``object

The signed-in user, for a dashboard session.

InboundRawResponse

FieldDescription

count``integerRequired

Number of messages stored (one per recipient inbox that accepted it).

messages Message[] Required

The stored messages, marked received_via: "raw".

errors``object[]

Recipients that could not be delivered to, when there were several and at least one succeeded.

held``object[]

Recipients whose copy was held (not delivered yet) because the organization reached a Free plan limit: monthly, daily or storage, or queued behind mail already held. Held mail is delivered when the allowance resets or after an upgrade.

Inbox

FieldDescription

pod_id``stringRequired

ID of the pod the inbox belongs to.

inbox_id``stringRequired

ID of the inbox: its email address, as in AgentMail (inbox_id == email).

email``stringRequired

Email address of the inbox.

display_name``string

Display name: Display Name username@domain.com.

client_id``string

Client ID given at creation (idempotency key).

status``"active" | "paused"Required

metadata``Record<string, string | number | boolean>

Custom key-value pairs attached to the inbox.

updated_at``string (date-time)Required

Time at which the inbox was last updated.

created_at``string (date-time)Required

Time at which the inbox was created.

organization_id``stringRequired

ID of the organization.

ephemeral``booleanRequired

Whether the inbox expires (see ttl_seconds).

ttl_seconds``integer

TTL of an ephemeral inbox. Each inbound message pushes expires_at to now + ttl_seconds.

expires_at``string (date-time)

When an ephemeral inbox and its mail are deleted.

created_by``"api" | "catch_all" | "dashboard" | "agent"Required

What created the inbox: the API, a catch-all domain, the dashboard or an agent registration.

InboxAvailability

FieldDescription

available``booleanRequired

email``stringRequired

The address that was checked (lowercased).

reason``"invalid_username" | "domain_not_found" | "taken"

Why the address is not available.

message``string

Human-readable reason.

Invitation

An invitation to join the organization.

FieldDescription

invitation_id``stringRequired

ID of the invitation.

organization_id``stringRequired

ID of the organization the invitee joins.

email``stringRequired

Address the invitation was sent to. Only this address can accept it.

role``"owner" | "admin" | "member"Required

Role in the organization. Owners and admins invite, change roles and remove members; only owners grant or remove the owner role, and an organization always keeps one owner.

state``"pending" | "accepted" | "expired" | "revoked"Required

State of the invitation.

invited_by_user_id``string

ID of the member who sent it, when known.

expires_at``string (date-time)Required

When the invitation stops working (7 days after it was sent).

created_at``string (date-time)Required

When the invitation was sent.

InvitationPreviewResponse

What an invitation link is for, before signing in.

FieldDescription

organization_name``stringRequired

The organization the invitation is to.

email``stringRequired

The invited address, masked (a••@example.com).

state``"pending" | "accepted" | "expired" | "revoked"Required

Only a pending invitation can be accepted.

expires_at``string (date-time)Required

When the invitation expires.

JsonRpcError

JSON-RPC 2.0 error response.

FieldDescription

jsonrpc``"2.0"Required

error``objectRequired

id``string | number | nullRequired

JsonWebKeySet

RFC 7517 JWK Set.

FieldDescription

keys``Record<string, unknown>[]Required

ListAgentRegistrationsResponse

FieldDescription

count``integerRequired

Number of items returned.

limit``integer

Maximum number of items per page. Default 50, maximum 500; larger values are capped.

next_page_token``string

Page token for pagination. Absent on the last page.

agent_registrations AgentRegistration[] Required

Newest first unless ascending is set.

ListApiKeysResponse

FieldDescription

count``integerRequired

Number of items returned.

limit``integerRequired

Page size used.

next_page_token``string

Page token for pagination. Absent on the last page.

api_keys BearerApiKey[] Required

Keys in the route scope that are not revoked, ordered by created_at, newest first unless ascending is set.

ListDeliveriesResponse

FieldDescription

count``integerRequired

Number of items returned.

limit``integer

Maximum number of items per page. Default 50, maximum 500; larger values are capped.

next_page_token``string

Page token for pagination. Absent on the last page.

deliveries WebhookDelivery[] Required

Ordered by created_at, newest first unless ascending is set.

ListDomainsResponse

FieldDescription

count``integerRequired

Number of items returned.

limit``integer

Maximum number of items per page. Default 50, maximum 500; larger values are capped.

next_page_token``string

Page token for pagination. Absent on the last page.

domains DomainItem[] Required

Ordered by created_at, newest first unless ascending is set.

ListDraftsResponse

FieldDescription

count``integerRequired

Number of items returned.

limit``integer

Maximum number of items per page. Default 50, maximum 500; larger values are capped.

next_page_token``string

Page token for pagination. Absent on the last page.

drafts DraftItem[] Required

Ordered by created_at, newest first unless ascending is set.

ListEntry

An allow or block list entry. The route sets the list: /v0/lists is the organization list, /v0/pods/{pod_id}/lists the pod list, /v0/inboxes/{inbox_id}/lists the inbox list.

FieldDescription

entry``stringRequired

Email address or domain (lowercased).

organization_id``stringRequired

ID of the organization.

pod_id``string

ID of the pod, for pod-scoped entries.

inbox_id``string

ID of the inbox, for inbox-scoped entries.

reason``string

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_only``booleanRequired

Always false: every entry can be deleted through the API.

created_at``string (date-time)Required

Time at which the entry was created.

ListEventsResponse

FieldDescription

count``integerRequired

Number of items returned.

limit``integer

Maximum number of items per page. Default 50, maximum 500; larger values are capped.

next_page_token``string

Page token for pagination. Absent on the last page.

events Event[] Required

Newest first; oldest first when after is set or ascending is true.

ListInboxesResponse

FieldDescription

count``integerRequired

Number of items returned.

limit``integer

Maximum number of items per page. Default 50, maximum 500; larger values are capped.

next_page_token``string

Page token for pagination. Absent on the last page.

inboxes Inbox[] Required

Ordered by created_at, newest first unless ascending is set.

ListInvitationsResponse

FieldDescription

count``integerRequired

Number of items returned.

limit``integer

Maximum number of items per page. Default 50, maximum 500; larger values are capped.

next_page_token``string

Page token for pagination. Absent on the last page.

invitations Invitation[] Required

Pending invitations, newest first.

ListListEntriesResponse

FieldDescription

count``integerRequired

Number of items returned.

limit``integer

Maximum number of items per page. Default 50, maximum 500; larger values are capped.

next_page_token``string

Page token for pagination. Absent on the last page.

entries ListEntry[] Required

Ordered by entry, ascending unless ascending is false.

ListMembersResponse

FieldDescription

count``integerRequired

Number of items returned.

limit``integer

Maximum number of items per page. Default 50, maximum 500; larger values are capped.

next_page_token``string

Page token for pagination. Absent on the last page.

members Member[] Required

Oldest first unless ascending=false.

ListMessagesResponse

FieldDescription

count``integerRequired

Number of items returned.

limit``integer

Maximum number of items per page. Default 50, maximum 500; larger values are capped.

next_page_token``string

Page token for pagination. Absent on the last page.

messages MessageItem[] Required

Ordered by timestamp, newest first unless ascending is set.

ListOAuthGrantsResponse

FieldDescription

count``integerRequired

Number of items returned.

limit``integer

Maximum number of items per page. Default 50, maximum 500; larger values are capped.

next_page_token``string

Page token for pagination. Absent on the last page.

oauth_grants OAuthGrant[] Required

Newest first unless ascending is set.

ListPasskeysResponse

FieldDescription

passkeys Passkey[] Required

The person’s passkeys, oldest first.

email_codes``booleanRequired

Email sign-in codes work for this account. false once turned off (with at least one passkey).

step_up``objectRequired

Confirmation before sensitive changes.

prompt``booleanRequired

Offer to create a passkey (no passkey yet, and the offer was not snoozed or declined).

ListPodsResponse

FieldDescription

count``integerRequired

Number of items returned.

limit``integer

Maximum number of items per page. Default 50, maximum 500; larger values are capped.

next_page_token``string

Page token for pagination. Absent on the last page.

pods Pod[] Required

Ordered by created_at, newest first unless ascending is set. A pod credential sees only its pod.

ListSessionOrganizationsResponse

FieldDescription

organizations MembershipOrganization[] Required

Every organization the person belongs to, by name.

ListSuppressionsResponse

FieldDescription

count``integerRequired

Number of items returned.

limit``integer

Maximum number of items per page. Default 50, maximum 500; larger values are capped.

next_page_token``string

Page token for pagination. Absent on the last page.

suppressions Suppression[] Required

Newest first unless ascending is set.

ListThreadsResponse

FieldDescription

count``integerRequired

Number of items returned.

limit``integer

Maximum number of items per page. Default 50, maximum 500; larger values are capped.

next_page_token``string

Page token for pagination. Absent on the last page.

threads ThreadItem[] Required

Ordered by timestamp, newest first unless ascending is set.

truncated``true

Present when q matched more than 500 messages: only the threads of the newest 500 matching messages were considered.

ListTrustedDomainsResponse

FieldDescription

count``integerRequired

Number of items returned.

limit``integer

Maximum number of items per page. Default 50, maximum 500; larger values are capped.

next_page_token``string

Page token for pagination. Absent on the last page.

trusted_domains TrustedDomain[] Required

Entries stored at exactly this level (organization, pod or inbox), newest first unless ascending is set.

ListWebhooksResponse

FieldDescription

count``integerRequired

Number of items returned.

limit``integer

Maximum number of items per page. Default 50, maximum 500; larger values are capped.

next_page_token``string

Page token for pagination. Absent on the last page.

webhooks Webhook[] Required

Ordered by created_at, newest first unless ascending is set.

LoginRequest

FieldDescription

email``stringRequired

password``stringRequired

MagicLinkRequest

FieldDescription

email``stringRequired

Address to send the sign-in link to.

org_name``string

Organization name, used only when this is the address’s first sign-in.

next``string

Same-origin path to land on after sign-in, for example /claim?user_code=123456. Anything else is ignored. Default /app.

organization_name``string

Alias of org_name.

organizationName``stringDeprecated

Alias of org_name.

MagicLinkResponse

FieldDescription

ok``trueRequired

McpDescription

How to connect to the remote MCP server.

FieldDescription

name``stringRequired

description``stringRequired

What the server is for, in one line.

icons``object[]Required

The MachineMail mark, for clients and registries that show an icon.

version``stringRequired

transport``"streamable-http"Required

url``stringRequired

The canonical MCP endpoint, https://mcp.machinemail.dev/mcp. https://machinemail.dev/mcp also works (legacy alias).

authentication``objectRequired

docs``stringRequired

Member

A person in the organization, with their role there and how they sign in.

FieldDescription

user_id``stringRequired

ID of the user.

email``stringRequired

Email address the user signs in with.

name``string | null

Display name, when set.

organization_id``stringRequired

ID of the organization this record is about: the session’s active organization, or the organization listed.

role``"owner" | "admin" | "member"Required

created_at``string (date-time)Required

When the user was created.

sign_in_methods``("email" | "password" | "google" | "github" | "apple" | "microsoft" | "sso" | "passkey")[]Required

Every method the member has used to sign in to this organization, in the order first used. Empty until their first sign-in after this was recorded.

last_sign_in_method``("email" | "password" | "google" | "github" | "apple" | "microsoft" | "sso" | "passkey" | null) | nullRequired

How the member last signed in to this organization. null until their first sign-in after this was recorded.

MembershipOrganization

An organization the signed-in person belongs to.

FieldDescription

organization_id``stringRequired

ID of the organization.

name``stringRequired

Name of the organization.

slug``stringRequired

URL-safe name of the organization. Fixed when the organization is created; it never changes.

role``"owner" | "admin" | "member"Required

current``booleanRequired

The session is signed in to this organization.

Message

FieldDescription

inbox_id``stringRequired

ID of the inbox.

thread_id``stringRequired

ID of the thread.

message_id``stringRequired

ID of the message.

labels``string[]Required

Labels of the message.

timestamp``string (date-time)Required

Time at which the message was sent or received.

from``stringRequired

Address of the sender. In format username@domain.com or Display Name username@domain.com.

to``string[]Required

Addresses of the recipients. In format username@domain.com or Display Name username@domain.com.

cc``string[]

Addresses of the CC recipients. In format username@domain.com or Display Name username@domain.com.

bcc``string[]

Addresses of the BCC recipients. In format username@domain.com or Display Name username@domain.com.

subject``string

Subject of the message.

preview``string

Text preview of the message.

attachments Attachment[]

Attachments of the message.

in_reply_to``string

ID of the message being replied to.

references``string[]

IDs of previous messages in the thread.

headers``Record<string, string>

Headers of the message.

authentication_results MessageAuthenticationResults

SPF, DKIM and DMARC verdicts for a received message, each with the domain it is about, as recorded when the message reached MachineMail: by the receiving mail provider (for example Amazon SES), or by the Authentication-Results header of the server that delivered it to MachineMail. A mechanism that was not evaluated is absent. The whole field is absent on sent messages, on messages injected through POST /inbound/raw (their headers are not believed), when nothing was evaluated, and on messages received before the field was introduced. As in AgentMail, only verdicts that speak for the sender are kept. spf is present only when spf_domain is aligned with the sender (shares an organizational domain with the From domain, or with the Sender domain when From spans several domains): an unaligned SPF result is withheld whatever its value. dkim and dmarc are withheld when From spans more than one domain or could not be parsed. Unlike the trust report (trust.authentication), which collapses each result to the values MachineMail scores on and adds aligned, these are the uncollapsed results: permerror and temperror stay as they are. dkim_domain is the signing domain as written: compare it with the From domain before treating a DKIM pass as proof of the sender, and use trust.level (or the UNAUTHENTICATED label) to decide whether to act on the message. Do not reject mail on dmarc: fail alone: forwarding breaks it.

size``integerRequired

Size of the message in bytes.

updated_at``string (date-time)Required

Time at which the message was last updated.

created_at``string (date-time)Required

Time at which the message was created.

pod_id``stringRequired

ID of the pod.

direction``"inbound" | "outbound"Required

Whether the message was received or sent.

delivery_status``"sent" | "delivered" | "bounced" | "complained"

Outbound only: last delivery state reported by the transport.

trust_level``"verified" | "known" | "unknown" | "suspicious" | "quarantined"

Inbound only: trust.level, for list badges.

reply_to``string[]

Reply-to addresses. In format username@domain.com or Display Name username@domain.com.

text``string

Plain text body. Untrusted: agents should read trust.content.text or extracted_text.

html``string

HTML body. Untrusted.

extracted_text``string

New text content, without quoted replies.

extracted_html``string

New HTML content, without quoted replies.

received_via``"raw"

raw when the message was injected with POST /inbound/raw (authentication not verified).

held_at``string (date-time)

When the message arrived, for inbound mail that was held because the organization reached a Free plan limit. created_at is then when it was delivered (released).

trust TrustReport

Trust report of an inbound message.

MessageAuthenticationResults

SPF, DKIM and DMARC verdicts for a received message, each with the domain it is about, as recorded when the message reached MachineMail: by the receiving mail provider (for example Amazon SES), or by the Authentication-Results header of the server that delivered it to MachineMail. A mechanism that was not evaluated is absent. The whole field is absent on sent messages, on messages injected through POST /inbound/raw (their headers are not believed), when nothing was evaluated, and on messages received before the field was introduced.

As in AgentMail, only verdicts that speak for the sender are kept. spf is present only when spf_domain is aligned with the sender (shares an organizational domain with the From domain, or with the Sender domain when From spans several domains): an unaligned SPF result is withheld whatever its value. dkim and dmarc are withheld when From spans more than one domain or could not be parsed.

Unlike the trust report (trust.authentication), which collapses each result to the values MachineMail scores on and adds aligned, these are the uncollapsed results: permerror and temperror stay as they are. dkim_domain is the signing domain as written: compare it with the From domain before treating a DKIM pass as proof of the sender, and use trust.level (or the UNAUTHENTICATED label) to decide whether to act on the message. Do not reject mail on dmarc: fail alone: forwarding breaks it.

FieldDescription

spf``"pass" | "fail" | "none" | "neutral" | "softfail" | "temperror" | "permerror"

Result of one authentication mechanism, in the vocabulary of the Authentication-Results header (RFC 8601). none: there was nothing to evaluate (no SPF record for the envelope sender domain, no DKIM signature, or no DMARC record for the From domain). temperror: the check could not complete, for example a DNS timeout.

dkim``"pass" | "fail" | "none" | "neutral" | "softfail" | "temperror" | "permerror"

dmarc``"pass" | "fail" | "none" | "neutral" | "softfail" | "temperror" | "permerror"

spf_domain``string

Envelope sender (MAIL FROM) domain the spf verdict is about (smtp.mailfrom, or the HELO name when the envelope sender was empty).

dkim_domain``string

Signing domain (d=) of the signature the dkim verdict is about: for pass, a signature that passed, preferring one aligned with the From domain. Present only when dkim is pass or fail. It is the domain as signed: compare it with the From domain before relying on it.

dmarc_domain``string

From domain the dmarc verdict is about (header.from).

arc_sealer``string

Domain of the forwarder whose ARC seal the verdicts were read from (for example google.com): they then describe the message as that forwarder received it. Present only on forwarded mail, and only beside at least one verdict. MachineMail does not validate ARC chains, so it reads verdicts from ARC only when its trust layer is set to believe any results header; by default it believes only its own receiving server and does not send this key.

MessageItem

A message without its bodies, as in lists.

FieldDescription

inbox_id``stringRequired

ID of the inbox.

thread_id``stringRequired

ID of the thread.

message_id``stringRequired

ID of the message.

labels``string[]Required

Labels of the message.

timestamp``string (date-time)Required

Time at which the message was sent or received.

from``stringRequired

Address of the sender. In format username@domain.com or Display Name username@domain.com.

to``string[]Required

Addresses of the recipients. In format username@domain.com or Display Name username@domain.com.

cc``string[]

Addresses of the CC recipients. In format username@domain.com or Display Name username@domain.com.

bcc``string[]

Addresses of the BCC recipients. In format username@domain.com or Display Name username@domain.com.

subject``string

Subject of the message.

preview``string

Text preview of the message.

attachments Attachment[]

Attachments of the message.

in_reply_to``string

ID of the message being replied to.

references``string[]

IDs of previous messages in the thread.

headers``Record<string, string>

Headers of the message.

authentication_results MessageAuthenticationResults

size``integerRequired

Size of the message in bytes.

updated_at``string (date-time)Required

Time at which the message was last updated.

created_at``string (date-time)Required

Time at which the message was created.

pod_id``stringRequired

ID of the pod.

direction``"inbound" | "outbound"Required

Whether the message was received or sent.

delivery_status``"sent" | "delivered" | "bounced" | "complained"

Outbound only: last delivery state reported by the transport.

trust_level``"verified" | "known" | "unknown" | "suspicious" | "quarantined"

Inbound only: trust.level, for list badges.

MetricBucket

FieldDescription

timestamp``string (date-time)Required

Start of the bucket.

count``integerRequired

Number of events in the bucket.

OAuthApproveRequest

FieldDescription

request_id``stringRequired

pod_id``string

Limit the grant to one pod of the organization. Default: the whole organization.

inbox_id``string

Limit the grant to one inbox (and its pod).

organization_id``string

The organization the grant is for, as the consent page showed it: it must be the one the session is signed in to (409 conflict otherwise, for example after another tab switched organizations). To connect the app to another organization the person belongs to, switch the session to it first (POST /auth/organizations/switch). Default: the session’s organization.

OAuthAuthorizationRequest

A pending authorization request, as the consent page shows it.

FieldDescription

request_id``stringRequired

client OAuthClientInfo Required

redirect_uri``stringRequired

Where the response goes.

redirect_host``stringRequired

Host (or scheme, for an app link) of redirect_uri, for the human to check.

redirect_loopback``booleanRequired

The response goes to a program on this computer (http://127.0.0.1, localhost).

resource``stringRequired

What the token will be good for: the MCP server (https://mcp.machinemail.dev/mcp, or the legacy /mcp) or / (the REST API and MCP).

scopes ScopeDescription[] Required

What the client asked for.

created_at``string (date-time)Required

expires_at``string (date-time)Required

When the request expires (10 minutes after it was made).

OAuthClientInfo

FieldDescription

client_id``stringRequired

client_name``string | nullRequired

Self-reported by the client.

client_uri``string | nullRequired

Self-reported; https only.

logo_uri``string | nullRequired

Self-reported; https only.

registration``"dynamic" | "metadata_document"Required

dynamic: registered at /oauth2/register (name and logo unverified). metadata_document: client_id is the URL of its metadata document, so its host is verified.

host``string | nullRequired

metadata_document: the host that serves the document (for example claude.ai).

OAuthDecision

FieldDescription

status``"approved" | "denied"Required

redirect_to``stringRequired

Send the browser here: redirect_uri with code (or error=access_denied), state and iss.

OAuthDenyRequest

FieldDescription

request_id``stringRequired

OAuthError

OAuth / auth.md error body (RFC 6749 section 5.2, RFC 7591 section 3.2.2). The /agent/* and /oauth2/* endpoints use this shape instead of the API error envelope.

FieldDescription

error``stringRequired

Error code: invalid_request, invalid_grant, invalid_client, invalid_target, invalid_scope, invalid_client_metadata, invalid_redirect_uri, unsupported_grant_type, unsupported_response_type, access_denied, authorization_pending, slow_down, expired_token, interaction_required, login_required, invalid_claim_token, claimed_or_in_flight, claim_expired, rate_limited, anonymous_not_enabled, service_auth_not_enabled, identity_assertion_not_enabled, invalid_issuer, invalid_signature, invalid_audience, expired, replay_detected, invalid_client_id, missing_verified_email.

error_description``stringRequired

message``stringRequired

Same text as error_description.

registration_id``string

interaction_required only.

agent_id``string

interaction_required only.

registration_type``"anonymous" | "service_auth" | "identity_assertion"

interaction_required only.

claim_url``string

interaction_required only.

claim_token``string

interaction_required only.

claim_token_expires``string (date-time)

interaction_required only.

interaction_required only.

claim``object

interaction_required only.

max_age``integer

login_required only: the maximum auth_time age in seconds.

OAuthGrant

An app a person connected with OAuth. Revoking it ends its access and refresh tokens at once.

FieldDescription

grant_id``stringRequired

ID of the grant (oag_...).

client_id``stringRequired

client_name``string | nullRequired

Self-reported by the client at registration.

client_uri``string | nullRequired

logo_uri``string | nullRequired

registration``"dynamic" | "metadata_document"Required

user_id``stringRequired

Who approved it.

user_email``string | nullRequired

scopes``("inboxes.read" | "inboxes.write" | "messages.read" | "messages.send" | "messages.write" | "webhooks.read" | "webhooks.write" | "domains.read" | "domains.write" | "lists.read" | "lists.write" | "metrics.read" | "pods.read" | "pods.write" | "api_keys.read" | "api_keys.write")[]Required

resource``stringRequired

Audience of its access tokens.

pod_id``string | nullRequired

Set when the grant is limited to one pod.

inbox_id``string | nullRequired

Set when the grant is limited to one inbox.

created_at``string (date-time)Required

last_used_at``string (date-time) | nullRequired

Last token refresh or API call (updated at most once a minute).

expires_at``string (date-time)Required

When the current refresh token expires unless it is used (30 days after the last refresh).

OkResponse

Acknowledgement.

FieldDescription

ok``trueRequired

OneTimeApiKey

An API key with its plaintext secret, returned once.

FieldDescription

api_key_id``stringRequired

ID of the API key.

api_key``stringRequired

Plaintext secret (mm_live_...). Shown once.

prefix``stringRequired

First characters of the key, shown in listings.

name``stringRequired

Name of the key.

created_at``string (date-time)Required

When the key was created.

Organization

The organization of the credential. plan and GET /v0/organizations/usage report plan allowances; inboxes are unlimited (no inbox_limit) and there are no billing fields.

FieldDescription

organization_id``stringRequired

ID of the organization.

name``stringRequired

Name of the organization.

slug``stringRequired

URL-safe name of the organization, chosen from its name when it is created. It never changes, not even when the organization is renamed. {slug}@ on the shared domain is reserved for this organization: no other organization can create that inbox.

plan``"free" | "pro" | "team" | "scale"Required

Plan of the organization.

inbox_count``integerRequired

Number of inboxes in the credential scope.

domain_count``integerRequired

Number of domains in the organization.

domain_limit``integer

Custom domains included in the plan. The Free plan cannot add more; paid plans can, and each extra domain is billed. Always present on GET /v0/organizations and PATCH /v0/organizations.

usage``object

Usage. Always present on GET /v0/organizations and PATCH /v0/organizations.

shared_domain``string

Domain every organization can create inboxes on, used when an inbox is created without domain. Always present on GET /v0/organizations and PATCH /v0/organizations.

undo_send``booleanRequired

Undo send in the dashboard: when true (the default), a message sent from the MachineMail dashboard waits 5 seconds before it goes out, so it can be undone. Only the dashboard reads it: the API, the MCP server and the CLI always send at once.

default_inbox_id``string | nullRequired

The default inbox of the organization (its inbox_id). A new organization gets {slug}@ on the shared domain, named after the organization, as its default inbox; when that address cannot be used (a reserved name), it starts without one. The dashboard lists the default inbox first. Change it with PATCH /v0/organizations. null when there is none: it was cleared, its inbox was deleted, or (for a pod or inbox credential) it is outside the credential scope.

updated_at``string (date-time)Required

Time at which the organization was last updated.

created_at``string (date-time)Required

Time at which the organization was created.

OrganizationDeletionStarted

A confirmation code was emailed to you.

FieldDescription

email``stringRequired

Where the code was sent: your own address, partly hidden.

expires_at``string (date-time)Required

When the code stops working (10 minutes after it was sent).

Passkey

A passkey the signed-in person can sign in with.

FieldDescription

passkey_id``stringRequired

ID of the passkey (pk_…).

name``stringRequired

Name shown in Settings (named after its password manager or device when added; up to 64 characters).

created_at``string (date-time)Required

When the passkey was added.

last_used_at``string (date-time) | nullRequired

When it last signed in or confirmed a change.

backed_up``booleanRequired

Synced by its password manager to the person’s other devices.

device_type``"singleDevice" | "multiDevice"

multiDevice: a synced passkey. singleDevice: bound to one device or security key.

PasskeyCredentialRequest

FieldDescription

credential``Record<string, unknown>Required

The browser’s AuthenticationResponseJSON.

PasskeyOptionsResponse

FieldDescription

options``Record<string, unknown>Required

PublicKeyCredentialRequestOptionsJSON: pass to navigator.credentials.get().

PasskeyPromptRequest

FieldDescription

action``"not_now" | "never"Required

not_now: ask again in 14 days. never: don’t ask again.

PasskeyRegistrationOptionsResponse

FieldDescription

options``Record<string, unknown>Required

PublicKeyCredentialCreationOptionsJSON: pass to navigator.credentials.create().

PasskeySignInOptionsRequest

FieldDescription

next``string

Same-origin path to land on after sign-in. Anything else is ignored. Default /app.

invitation_token``string

An invitation token (from /invite/{token}): signing in accepts the invitation.

PendingOrganizationRequest

FieldDescription

organization_id``stringRequired

One of the organizations from GET /auth/pending.

PendingSignInResponse

The sign-in in progress in this browser.

FieldDescription

step``"code" | "organization" | "verify_email"Required

code: waiting for the emailed sign-in code. organization: pick an organization. verify_email: enter the code that verifies the email.

email``string

The address signing in, when known.

organizations``object[]

For organization: the organizations to pick from.

invitation``booleanRequired

Signing in accepts an invitation.

PendingVerifyRequest

FieldDescription

code``stringRequired

The 6-digit code from the email. Spaces and dashes are ignored.

PlanLimits

The allowances that apply to the organization.

FieldDescription

messages_per_month``integer | nullRequired

Inbound messages and outbound recipients together per calendar month (UTC). null: no combined cap (paid plans).

messages_per_day``integer | nullRequired

The same, per UTC day. null: no daily cap.

inbound_per_month``integer | nullRequired

Inbound messages included per month on paid plans (more is billed as overage). null on Free.

outbound_per_month``integer | nullRequired

Outbound recipients included per month on paid plans (more is billed as overage). null on Free.

storage_bytes``integerRequired

Storage included, in bytes (1 GB = 1,000,000,000 bytes).

custom_domains``integerRequired

Custom domains included.

seats``integer | nullRequired

Members (including pending invitations). null: unlimited.

overage``booleanRequired

true: usage past an allowance is billed, never blocked. false (Free): inbound past it is held and sending is refused until the reset.

PlanUsage

Plan allowances and usage of the organization in the current period.

FieldDescription

plan``"free" | "pro" | "team" | "scale"Required

Plan of the organization: free, pro, team or scale.

period``objectRequired

limits PlanLimits Required

The allowances that apply to the organization.

usage``objectRequired

held``objectRequired

enforcement``"enforce" | "shadow" | "off" | "exempt"Required

enforce: limits apply. shadow and off: limits are not applied right now (usage is still counted). exempt: this organization has its own limits (unclaimed agent sandbox).

Pod

FieldDescription

pod_id``stringRequired

ID of the pod.

organization_id``stringRequired

ID of the organization.

name``stringRequired

Name of the pod.

is_default``booleanRequired

Whether this is the default pod, where inboxes go when no pod is given. It cannot be deleted.

client_id``string

Client ID given at creation (idempotency key).

updated_at``string (date-time)Required

Time at which the pod was last updated.

created_at``string (date-time)Required

Time at which the pod was created.

PreviewTrustedDomainRequest

FieldDescription

domain``stringRequired

include_subdomains``boolean

As for create.

PreviewTrustedDomainResponse

What a create would do, without saving anything.

FieldDescription

domain``string | nullRequired

The entry as it would be stored (ASCII form). null when it is not a domain or address.

domain_unicode``string | nullRequired

The same in Unicode form.

entry_type``objectRequired

allowed``booleanRequired

Whether a create would be accepted (with confirm: true when confirmation_required), plan limit aside.

refusal``("free_mail" | "privacy_relay" | "shared_platform" | "public_suffix" | "disposable" | "invalid" | "confusable_idn" | null) | nullRequired

Why it cannot be trusted. null when it can.

message``string | nullRequired

The refusal or confirmation, in one sentence. null when there is neither.

confirmation_required``booleanRequired

A platform where anyone can write the content, or a relay address: a create needs confirm: true.

warnings Warning[] Required

Conflicts with block entries or allow-only scopes, as a create would report them.

would_release``object | nullRequired

Not computed yet: always null.

suggestions``string[] | nullRequired

Narrower entries to consider (an exact address). Not computed yet: always null.

ProtectedResourceMetadata

RFC 9728 OAuth Protected Resource Metadata.

FieldDescription

resource``stringRequired

authorization_servers``string[]Required

bearer_methods_supported``string[]Required

header.

resource_name``stringRequired

resource_logo_uri``stringRequired

resource_documentation``stringRequired

The /auth.md document, or the MCP guide for /mcp.

RatePoint

FieldDescription

timestamp``string (date-time)Required

End of the window the point covers; the window is the window seconds before it.

rate``number

Bounced (or complained) messages divided by messages sent over the window, as a fraction (0.05 is 5%). Absent when nothing was sent in the window.

sent``integerRequired

Messages sent in the window.

ReadyResponse

FieldDescription

status``"ready" | "unavailable"Required

ready when storage answers; the HTTP status is then 200, otherwise 503.

checks``objectRequired

The checks behind status.

Recipient

FieldDescription

address``stringRequired

Recipient address.

status``stringRequired

bounced or complained.

RegisterPasskeyRequest

FieldDescription

credential``Record<string, unknown>Required

The browser’s RegistrationResponseJSON.

name``string

Name for the passkey (up to 64 characters). Default: its password manager or device, or “Passkey”.

Reject

FieldDescription

inbox_id``stringRequired

ID of the inbox.

thread_id``nullRequired

Always null: nothing was stored.

message_id``nullRequired

Always null: nothing was stored.

timestamp``string (date-time)Required

When it happened.

reason``"inbox_paused" | "plan_limit" | "plan_limit_expired"Required

Why the message was rejected. inbox_paused: the inbox is paused. plan_limit (MachineMail): the organization reached a Free plan limit and already holds as much mail as it may. plan_limit_expired (MachineMail): held mail was not released in time and was deleted.

from``stringRequired

Sender of the rejected message.

subject``string

Subject of the rejected message.

RemovePasskeyResponse

FieldDescription

ok``trueRequired

sessions_ended``integerRequired

Sessions the passkey had signed in that were signed out.

signed_out``booleanRequired

This session was one of them: sign in again.

RenamePasskeyRequest

FieldDescription

name``stringRequired

New name, 1 to 64 characters.

ReplyAllMessageRequest

FieldDescription

labels``string | string[]

Labels of the message. SENT is always added.

reply_to``string | string[]

Reply-to address or addresses.

text``string

Plain text body.

html``string

HTML body.

attachments SendAttachment[]

Attachments to include.

headers``Record<string, string>

Headers to include. In-Reply-To and References also thread the message.

to``string | string[]

More recipients, added to the sender and recipients of the original.

cc``string | string[]

More CC recipients, added to the CC recipients of the original.

bcc``string | string[]

BCC recipient address or addresses.

subject``string

Subject of the reply. Defaults to the original subject with Re: in front.

ReplyToMessageRequest

FieldDescription

labels``string | string[]

Labels of the message. SENT is always added.

reply_to``string | string[]

Reply-to address or addresses.

to``string | string[]

Recipient address or addresses. Defaults to the sender of the original (its reply-to addresses if any); for an outbound original, its recipients.

cc``string | string[]

CC recipient address or addresses.

bcc``string | string[]

BCC recipient address or addresses.

reply_all``boolean

true replies to all recipients of the original, as Reply All Message does; to and cc are then added to them.

text``string

Plain text body.

html``string

HTML body.

attachments SendAttachment[]

Attachments to include.

headers``Record<string, string>

Headers to include. In-Reply-To and References also thread the message.

subject``string

Subject of the reply. Defaults to the original subject with Re: in front.

RevokeOtherSessionsResponse

FieldDescription

ok``trueRequired

ended``integerRequired

Other sessions signed out.

RevokeRequest

FieldDescription

token``stringRequired

An access token, a refresh token or an identity assertion.

token_type_hint``string

access_token, refresh_token or identity_assertion. A refresh token revokes its whole grant; an identity assertion its whole registration. Other values are ignored.

client_id``string

Refresh and access tokens of an app: when given, must be the client the token was issued to, or nothing is revoked.

client_secret``string

A confidential client authenticates as at the token endpoint (client_secret_post, or HTTP Basic).

ScopeDescription

FieldDescription

scope``"inboxes.read" | "inboxes.write" | "messages.read" | "messages.send" | "messages.write" | "webhooks.read" | "webhooks.write" | "domains.read" | "domains.write" | "lists.read" | "lists.write" | "metrics.read" | "pods.read" | "pods.write" | "api_keys.read" | "api_keys.write"Required

OAuth scope. Each grants API key permissions: inboxes.* (inbox_*), messages.read (message, thread and label reads), messages.send (send, reply, drafts), messages.write (update and delete messages and threads), webhooks.*, domains.*, lists.* (allow/block lists and suppressions), pods.*, api_keys.*, metrics.read (metrics and the event log).

description``stringRequired

SearchInboxesResponse

FieldDescription

count``integerRequired

Number of items returned.

limit``integer

Maximum number of items per page. Default 50, maximum 500; larger values are capped.

next_page_token``string

Page token for pagination. Absent on the last page.

inboxes Inbox[] Required

Matching inboxes, newest first.

truncated``true

Present when the organization has more than 500 inboxes in scope: only the newest 500 were searched.

SearchMessagesResponse

FieldDescription

count``integerRequired

Number of items returned.

limit``integer

Maximum number of items per page. Default 50, maximum 500; larger values are capped.

next_page_token``string

Page token for pagination. Absent on the last page.

messages MessageItem[] Required

Matching messages, newest first unless ascending is set.

SearchThreadsResponse

FieldDescription

count``integerRequired

Number of items returned.

limit``integer

Maximum number of items per page. Default 50, maximum 500; larger values are capped.

next_page_token``string

Page token for pagination. Absent on the last page.

threads ThreadItem[] Required

Matching threads, ordered by timestamp, newest first unless ascending is set.

truncated``true

Present when q matched more than 500 messages: only the threads of the newest 500 matching messages were considered.

Send

FieldDescription

inbox_id``stringRequired

ID of the inbox.

thread_id``stringRequired

ID of the thread.

message_id``stringRequired

ID of the message.

timestamp``string (date-time)Required

When it happened.

recipients``string[]Required

Every recipient (to, cc and bcc).

SendAttachment

Provide either content or url for each attachment.

FieldDescription

filename``string

Filename of the attachment. Defaults to the last segment of url.

content_type``string

Content type of the attachment. Defaults to the Content-Type of the url response.

content_disposition``"inline" | "attachment"

Content disposition of the attachment.

content_id``string

Content ID, for inline images referenced as cid: in the HTML body.

content``string

Base64 encoded content of the attachment.

url``string

URL the API downloads the attachment from: public http(s) only, no redirects, at most 10 MB, 20 second timeout.

SendMessageRequest

FieldDescription

labels``string | string[]

Labels of the message. SENT is always added.

reply_to``string | string[]

Reply-to address or addresses.

to``string | string[]

Recipient address or addresses.

cc``string | string[]

CC recipient address or addresses.

bcc``string | string[]

BCC recipient address or addresses.

subject``string

Subject of the message.

text``string

Plain text body.

html``string

HTML body.

attachments SendAttachment[]

Attachments to include.

headers``Record<string, string>

Headers to include. In-Reply-To and References also thread the message.

SendMessageResponse

FieldDescription

message_id``stringRequired

ID of the message.

thread_id``stringRequired

ID of the thread.

timestamp``string (date-time)Required

When the message was sent.

SessionResponse

The signed-in user and their organization.

FieldDescription

user User Required

A person who signs in to the dashboard.

organization Organization Required

The organization of the credential. plan and GET /v0/organizations/usage report plan allowances; inboxes are unlimited (no inbox_limit) and there are no billing fields.

SetError

RFC 8935 SET delivery error.

FieldDescription

err``stringRequired

invalid_request, invalid_issuer, invalid_key or invalid_audience.

description``stringRequired

SignInStepResponse

The result of a sign-in step.

FieldDescription

ok``trueRequired

signed_in``booleanRequired

true: the mm_session cookie is set. false: another step comes first (organization picker, email verification, SSO).

redirect_to``stringRequired

Where to send the browser next, built by the server: next (with welcome=1 after a first sign-in), /login/organization, /login/verify, an identity provider, or /login?error=.