Skip to content
machinemail

Objects

Every object the API accepts or returns, field by field.

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

AgentIdentityRequest

type"anonymous" | "service_auth" | "identity_assertion"Required
Registration type.
namestring
Agent label (first 100 characters). Untrusted; shown as agent-described in the dashboard.
client_namestring
Alias of name.
login_hintstring
service_auth: email address of the user the agent acts for. Required for that type.
assertion_typestring
identity_assertion: urn:ietf:params:oauth:token-type:id-jag. Required for that type.
assertionstring
identity_assertion: the ID-JAG (signed JWT). Required for that type.

AgentIdentityResponse

registration_idstringRequired
agent_idstringRequired
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_assertionstring
Service-signed JWT to exchange at /oauth2/token. Absent for service_auth until the claim completes.
assertion_expiresstring (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_urlstring
Where to start the claim ceremony (/agent/identity/claim).
claim_tokenstring
Secret for /agent/identity/claim and the claim grant.
claim_token_expiresstring (date-time)
claimobject
service_auth registrations: the ceremony is already started.
inboxobject
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.

agent_idstringRequired
ID of the registration (reg_...).
registration_idstringRequired
Same value as agent_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.
status"pending_claim" | "claimed" | "revoked"Required
namestring
Agent-described label. Untrusted.
clientstring
Provider name for identity_assertion, otherwise agent (self-described) or anonymous agent.
organization_idstring
Organization the registration is bound to (after a claim, or right away for identity_assertion).
inbox_idstring
The sandbox inbox of an anonymous registration.
emailstring
Verified email bound at claim or carried by the identity assertion.
issuerstring
Issuer of the identity assertion (identity_assertion).
agent_platformstring
agent_platform claim of the identity assertion.
created_atstring (date-time)Required
When the agent registered.
claimed_atstring (date-time)
When a human claimed the registration.
revoked_atstring (date-time)
When the registration was revoked.
expires_atstring (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.

*boolean
Every permission except inbound_raw. {"*": true, "inbound_raw": true} is full access plus raw injection.
inbox_readboolean
Read inbox details.
inbox_createboolean
Create new inboxes.
inbox_updateboolean
Update inbox settings.
inbox_deleteboolean
Delete inboxes.
thread_readboolean
Read threads.
thread_deleteboolean
Delete threads.
message_readboolean
Read messages.
message_replyboolean
Reply and reply-all. message_send allows them too.
message_sendboolean
Send messages (and reply, reply-all, forward).
message_updateboolean
Update message labels. Also required to update threads.
message_deleteboolean
Delete messages.
label_spam_readboolean
Access messages labeled spam.
label_blocked_readboolean
Access messages labeled blocked.
label_unauthenticated_readboolean
Access messages labeled unauthenticated.
label_trash_readboolean
Access messages labeled trash.
draft_readboolean
Read drafts.
draft_createboolean
Create drafts.
draft_updateboolean
Update drafts.
draft_deleteboolean
Delete drafts.
draft_sendboolean
Send drafts.
webhook_readboolean
Read webhook configurations.
webhook_createboolean
Create webhooks.
webhook_updateboolean
Update webhooks.
webhook_deleteboolean
Delete webhooks.
domain_readboolean
Read domain details.
domain_createboolean
Create domains.
domain_updateboolean
Update domains.
domain_deleteboolean
Delete domains.
list_entry_readboolean
Read list entries and suppressions.
list_entry_createboolean
Create list entries and suppressions.
list_entry_deleteboolean
Delete list entries and suppressions.
metrics_readboolean
Read metrics and events.
api_key_readboolean
Read API keys.
api_key_createboolean
Create API keys.
api_key_updateboolean
Update API keys.
api_key_deleteboolean
Delete API keys.
pod_readboolean
Read pods.
pod_createboolean
Create pods.
pod_updateboolean
Update pods.
pod_deleteboolean
Delete pods.
inbound_rawboolean
Inject raw mail with POST /inbound/raw. Never implied by an unrestricted key or *: it must be granted by name.

Attachment

attachment_idstringRequired
ID of the attachment.
filenamestring
Filename of the attachment.
sizeintegerRequired
Size of the attachment in bytes.
content_typestring
Content type of the attachment.
content_dispositionstring
Content disposition of the attachment (inline or attachment).
content_idstring
Content ID of the attachment.

AttachmentResponse

attachment_idstringRequired
ID of the attachment.
filenamestring
Filename of the attachment.
sizeintegerRequired
Size of the attachment in bytes.
content_typestring
Content type of the attachment.
content_dispositionstring
Content disposition of the attachment (inline or attachment).
content_idstring
Content ID of the attachment.
download_urlstringRequired
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_atstring (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 this server.

workosbooleanRequired
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_codebooleanRequired
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 this server offers none.
magic_linkbooleanRequired
Local magic-link sign-in (POST /auth/magic-link) is available.
passwordbooleanRequired
The deprecated password endpoints are available.
authkitbooleanRequiredDeprecated
Deprecated: always false. Kept for older clients; see email_code.

AuthorizationServerMetadata

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

resourcestringRequired
The protected resource: <issuer>/ (the REST API and MCP), or <issuer>/<path> 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, <issuer>/mcp is the legacy MCP alias.
authorization_serversstring[]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_supportedstring[]Required
header.
issuerstringRequired
authorization_endpointstringRequired
<issuer>/oauth2/authorize: authorization code grant with PKCE (S256).
token_endpointstringRequired
registration_endpointstringRequired
<issuer>/oauth2/register: Dynamic Client Registration (RFC 7591), public or confidential clients.
revocation_endpointstringRequired
device_authorization_endpointstringRequired
<issuer>/auth/cli/device/code: the device grant of the MachineMail CLI (client_id machinemail-cli only).
jwks_uristringRequired
service_documentationstringRequired
grant_types_supportedstring[]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_supportedstring[]Required
code.
response_modes_supportedstring[]Required
query.
code_challenge_methods_supportedstring[]Required
S256.
token_endpoint_auth_methods_supportedstring[]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_supportedstring[]Required
Same as token_endpoint_auth_methods_supported.
client_id_metadata_document_supportedbooleanRequired
true: an https URL is accepted as client_id (OAuth Client ID Metadata Document).
authorization_response_iss_parameter_supportedbooleanRequired
true: authorization responses carry iss (RFC 9207).
agent_authobjectRequired

BatchGetMessagesRequest

message_idsstring[]Required
IDs of the messages to fetch. Only the first 100 distinct IDs are read.

BatchGetMessagesResponse

limitintegerRequired
Number of IDs in the request.
countintegerRequired
Number of messages returned.
messagesMessage[]Required
Found messages, in request order. IDs not found in the inbox are omitted.

BatchUpdateMessagesRequest

message_idsstring[]Required
IDs of the messages to update. Only the first 100 distinct IDs are updated.
add_labelsstring | string[]
Label or labels to add to every message.
remove_labelsstring | string[]
Label or labels to remove from every message.

BatchUpdateMessagesResponse

limitintegerRequired
Number of IDs in the request.
countintegerRequired
Number of messages updated.
updatesUpdateMessageResponse[]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.

type"bearer"Required
Always bearer: MachineMail has no public-key credentials.
api_key_idstringRequired
ID of the API key.
prefixstringRequired
First 12 characters of the key (mm_live_ and 4 more), safe to display.
namestringRequired
Name of the key.
pod_idstring
Pod the key is scoped to: it can only access resources in this pod.
inbox_idstring
Inbox the key is scoped to: it can only access this inbox.
permissionsApiKeyPermissions
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.
created_atstring (date-time)Required
Time at which the key was created.
expires_atstring (date-time)
Time at which the key expires. Absent when it does not expire.
organization_idstringRequired
ID of the organization.
used_atstring (date-time)
Time at which the key was last used.
revoked_atstring (date-time)
When the key was deleted (revoked). Revoked keys are not listed but can still be fetched by ID.
updated_atstring (date-time)Required
Time at which the name, permissions or revocation last changed. Use does not change it.

Bounce

inbox_idstringRequired
ID of the inbox.
thread_idstringRequired
ID of the thread.
message_idstringRequired
ID of the message.
timestampstring (date-time)Required
When it happened.
typestringRequired
Bounce type: Permanent or Transient (or the provider type).
sub_typestringRequired
Bounce sub-type, General when the provider gives none.
recipientsRecipient[]Required
Bounced recipients. Permanent bounces are added to the suppression list.

ClaimBlock

RFC 8628-shaped claim ceremony block.

user_codestringRequired
6-digit code the human enters in the dashboard.
verification_uristringRequired
<PUBLIC_URL>/claim?claim_attempt_token=cat_...: the page to send the human to.
expires_inintegerRequired
Seconds until user_code expires.
intervalintegerRequired
Minimum seconds between /oauth2/token polls.

ClaimCompleteRequest

user_codestringRequired
The 6-digit code the agent shows; spaces and dashes are ignored.
claim_attempt_tokenstring
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.

agent_idstringRequired
ID of the registration (reg_...).
registration_idstringRequired
Same value as agent_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.
status"claimed"Required
namestring
Agent-described label. Untrusted.
clientstring
Provider name for identity_assertion, otherwise agent (self-described) or anonymous agent.
organization_idstringRequired
The organization of the signed-in user.
inbox_idstring
The sandbox inbox of an anonymous registration.
emailstring
Verified email bound at claim or carried by the identity assertion.
issuerstring
Issuer of the identity assertion (identity_assertion).
agent_platformstring
agent_platform claim of the identity assertion.
created_atstring (date-time)Required
When the agent registered.
claimed_atstring (date-time)
When a human claimed the registration.
revoked_atstring (date-time)
When the registration was revoked.
expires_atstring (date-time)
When an unclaimed registration expires.
inboxobject
The former sandbox inbox, now permanent and in the user’s default pod.

ClaimPreviewResponse

An agent registration plus the claim details.

agent_idstringRequired
ID of the registration (reg_...).
registration_idstringRequired
Same value as agent_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.
status"pending_claim" | "claimed" | "revoked"Required
namestring
Agent-described label. Untrusted.
clientstring
Provider name for identity_assertion, otherwise agent (self-described) or anonymous agent.
organization_idstring
Organization the registration is bound to (after a claim, or right away for identity_assertion).
inbox_idstring
The sandbox inbox of an anonymous registration.
emailstring
Verified email bound at claim or carried by the identity assertion.
issuerstring
Issuer of the identity assertion (identity_assertion).
agent_platformstring
agent_platform claim of the identity assertion.
created_atstring (date-time)Required
When the agent registered.
claimed_atstring (date-time)
When a human claimed the registration.
revoked_atstring (date-time)
When the registration was revoked.
expires_atstring (date-time)
When an unclaimed registration expires.
claim_emailstring
Only this user may claim the registration.
user_code_expires_atstring (date-time)
When the code expires.
sandbox_inboxobject
The sandbox inbox of an anonymous registration.

ClaimStartRequest

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

claim_tokenstring
Protocol form: the claim_token from registration.
emailstring
Binds the claim to this human. For service_auth and identity_assertion it must match the bound email.
agent_idstring
Alternative to claim_token; needs the registration’s access token or identity assertion as Authorization: Bearer.
registration_idstring
Alias of agent_id.

ClaimStartResponse

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

registration_idstringRequired
agent_idstringRequired
claim_attempt_idstringRequired
status"initiated"Required
expires_atstring (date-time)Required
When this attempt expires.
claim_attemptClaimBlockRequired
RFC 8628-shaped claim ceremony block.
user_codestringRequired
6-digit code the human enters in the dashboard.
verification_uristringRequired
<PUBLIC_URL>/claim?claim_attempt_token=cat_...: the page to send the human to.
expires_inintegerRequired
Seconds until user_code expires.
intervalintegerRequired
Minimum seconds between /oauth2/token polls.

CliDeviceAuthorization

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

user_codestringRequired
The code, formatted XXXX-XXXX.
device_idstringRequired
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_idstringRequired
Always machinemail-cli.
client_namestring | nullRequired
What the CLI says it is. Self-reported.
hostnamestring | nullRequired
The machine the CLI says it runs on. Self-reported.
key_namestringRequired
Name of the key approval creates: CLI on <hostname>.
permissionsstring[]Required
Permissions of that key: ["*"] (every permission except inbound_raw).
created_atstring (date-time)Required
When the CLI asked for the code.
expires_atstring (date-time)Required
When the code expires.

CliDeviceCodeRequest

client_idstringRequired
Always machinemail-cli.
client_namestring
Shown to the human on the approval page, for example MachineMail CLI 0.4.0. At most 100 characters. (max length 100)
hostnamestring
The machine the CLI runs on. Names the key (CLI on <hostname>) and is shown on the approval page. At most 253 characters. (max length 253)

CliDeviceCodeResponse

RFC 8628 device authorization response.

device_codestringRequired
Secret the CLI polls the token endpoint with. Never show it.
user_codestringRequired
Code the human checks on the approval page: 8 letters as XXXX-XXXX (consonants only, no look-alikes).
verification_uristringRequired
<PUBLIC_URL>/cli: where the human approves.
verification_uri_completestringRequired
verification_uri with ?code=<user_code>, for opening in a browser.
expires_inintegerRequired
Seconds until both codes expire (600).
intervalintegerRequired
Minimum seconds between polls of the token endpoint (5).

CliDeviceDecision

status"approved" | "denied"Required
key_namestringRequired
Name of the key the CLI receives (approved) or would have received (denied).

CliDeviceDecisionRequest

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

CliDeviceTokenRequest

grant_typestringRequired
urn:ietf:params:oauth:grant-type:device_code.
device_codestringRequired
The device_code from the device authorization response.
client_idstringRequired
Always machinemail-cli.

CliDeviceTokenResponse

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

access_tokenstringRequired
The new API key (mm_live_...). Returned once; send it as Authorization: Bearer.
token_type"Bearer"Required
api_key_idstringRequired
ID of the key, for DELETE /v0/api-keys/{api_key_id} on logout.
key_namestringRequired
Name of the key: CLI on <hostname>.
organizationOrganizationRequired
The organization the key belongs to.
userUserRequired
The person who approved the sign-in.

ClientRegistrationRequest

RFC 7591 client metadata. Unknown members are ignored.

redirect_urisstring[]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_namestring
Shown on the consent page, marked as unverified. At most 200 characters. (max length 200)
client_uristring
Home page of the client; shown on the consent page when it is https. (max length 2000)
logo_uristring
Logo shown on the consent page when it is https. (max length 2000)
token_endpoint_auth_methodstring
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_typesstring[]
authorization_code and refresh_token (the default). Must include authorization_code (invalid_client_metadata otherwise); other values are dropped from the registration.
response_typesstring[]
code (the default). Other values: invalid_client_metadata.
scopestring
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_idstring
Identifier of the client software. Stored, not verified. (max length 200)
software_versionstring
Version of the client software. Stored, not verified. (max length 100)

ClientRegistrationResponse

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

client_idstringRequired
The new client identifier (oac_...).
client_id_issued_atintegerRequired
Seconds since the epoch.
client_namestring
client_uristring
logo_uristring
redirect_urisstring[]Required
grant_typesstring[]Required
response_typesstring[]Required
token_endpoint_auth_method"none" | "client_secret_post" | "client_secret_basic"Required
As requested when supported, otherwise none.
client_secretstring
Confidential clients only (client_secret_post, client_secret_basic): shown once, stored only as a hash. Keep it secret.
client_secret_expires_atinteger
With client_secret: 0, the secret does not expire.
application_type"native" | "web"Required
scopestring
software_idstring
software_versionstring

Complaint

inbox_idstringRequired
ID of the inbox.
thread_idstringRequired
ID of the thread.
message_idstringRequired
ID of the message.
timestampstring (date-time)Required
When it happened.
typestringRequired
Complaint type, complaint when the provider gives none.
sub_typestringRequired
Complaint sub-type, abuse when the provider gives none.
recipientsRecipient[]Required
Complaining recipients, as {address, status} objects (AgentMail documents plain strings). They are added to the suppression list.

CreateApiKeyResponse

api_key_idstringRequired
ID of the API key.
prefixstringRequired
First 12 characters of the key (mm_live_ and 4 more), safe to display.
namestringRequired
Name of the key.
pod_idstring
Pod the key is scoped to: it can only access resources in this pod.
inbox_idstring
Inbox the key is scoped to: it can only access this inbox.
permissionsApiKeyPermissions
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.
created_atstring (date-time)Required
Time at which the key was created.
expires_atstring (date-time)
Time at which the key expires. Absent when it does not expire.
api_keystringRequired
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.

namestring
Name of the key. Default API key.
permissionsobject | null
Permissions of the new key. Omitted or null: full access for the key scope (inbound_raw excepted).
expires_atstring (date-time) | null
When the key stops working (a past time creates a key that is already expired). Omitted, the key does not expire. It cannot be changed later.

CreateDomainRequest

domainstringRequired
The domain name, for example example.com. Cannot be the shared domain or a domain another organization registered.
feedback_enabledboolean
Stored and returned; has no effect. Default false.
inbound_enabledboolean
Receive email for this domain. Default true. false makes it send-only (the inbound MX record is not required).
client_idstring
Idempotency key: a create with a client_id already used in the organization returns that domain with 200.
pod_idstring
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_allboolean
Create an inbox for any address at the domain that receives mail. Default false.
catch_all_ttl_secondsinteger | null
Make inboxes created by catch-all ephemeral with this TTL. null or absent: permanent.

CreateDraftRequest

labelsstring[]
Labels of the draft.
reply_tostring | string[]
Reply-to addresses: one address or a list.
tostring | string[]
Recipient addresses: one address or a list.
ccstring | string[]
CC addresses: one address or a list.
bccstring | string[]
BCC addresses: one address or a list.
subjectstring
Subject.
textstring
Plain text body.
htmlstring
HTML body.
attachmentsSendAttachment[]
Attachments, sent with the draft. Each needs content or url; a url is fetched when the draft is sent.
in_reply_tostring
ID of a message in this inbox to reply to: the sent message gets its In-Reply-To and References headers.
send_atstring (date-time) | null
Schedule the draft: it is sent automatically at this time (send_status: scheduled). null or absent: not scheduled.
client_idstring
Idempotency key: a create with a client_id already used in the organization returns that draft with 200.

CreateInboxRequest

usernamestring
Local part of the address: a-z, 0-9 and . _ + -, 1 to 64 characters. Randomly generated if omitted.
domainstring
Domain of the address: a domain verified by this organization. Defaults to the shared domain.
display_namestring
Display name: Display Name <username@domain.com>.
client_idstring
Idempotency key: a create with a client_id already used in the organization returns that inbox with 200.
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.
metadataRecord<string, string | number | boolean>
Custom key-value pairs attached to the inbox.
pod_idstring
Pod to create the inbox in. Defaults to the credential pod or the organization default pod.
ephemeralboolean
true without ttl_seconds creates an ephemeral inbox with a one hour TTL (3600 seconds).
ttl_secondsinteger | null
Creates an ephemeral inbox that expires ttl_seconds after creation, extended by each inbound message.

CreateInvitationRequest

emailstringRequired
Address to invite.
role"owner" | "admin" | "member"
Role on joining. Default member. Only owners can invite owners.

CreateListEntryRequest

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

CreatePodRequest

namestring
Name of the pod. Default Untitled pod.
client_idstring
Idempotency key: a create with a client_id already used in the organization returns that pod with 200.

CreateSessionOrganizationRequest

namestringRequired
Name of the new organization.

CreateSuppressionRequest

emailstringRequired
Address to suppress.
detailstring
Note stored as detail.
reasonstringDeprecated
Old name of detail (it is stored as detail; the suppression reason is always manual). Ignored when detail is set.

CreateWebhookRequest

urlstringRequired
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")[]
Event types the webhook receives. Omit it or send an empty array to receive every event type except domain.updated, which is sent only when listed.
client_idstring
Idempotency key: a create with a client_id already used in the organization returns that webhook with 200.
inbox_idsstring[]
Only deliver events of these inboxes.
pod_idsstring[]
Only deliver events of these pods.

Delivery

inbox_idstringRequired
ID of the inbox.
thread_idstringRequired
ID of the thread.
message_idstringRequired
ID of the message.
timestampstring (date-time)Required
When it happened.
recipientsstring[]Required
Delivered recipients.

Domain

pod_idstringRequired
ID of the pod the domain belongs to.
domain_idstringRequired
ID of the domain.
domainstringRequired
The domain name (for example example.com), lowercased.
feedback_enabledbooleanRequired
Stored as given. MachineMail does not send bounce and complaint notifications to inboxes; use the message.bounced and message.complained events.
inbound_enabledbooleanRequired
Receive email for this domain. false makes it send-only: the inbound MX record is not required.
subdomains_enabledbooleanRequired
Always false: inboxes on subdomains are not supported.
tracking_enabledbooleanRequired
Always false: open tracking is not supported.
client_idstring
Client ID given at creation (idempotency key).
updated_atstring (date-time)Required
Time at which the domain was last updated.
created_atstring (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. FAILED and VERIFYING are part of the enum but never set.
reasonstring
Why the domain is not verified yet: what to do next, or which records are missing or invalid. Absent once VERIFIED.
recordsVerificationRecord[]Required
DNS records to publish.
organization_idstringRequired
ID of the organization.
catch_allbooleanRequired
Mail to any address at the domain without an inbox creates one (created_by: catch_all).
catch_all_ttl_secondsinteger
TTL of inboxes created by catch-all; absent means they are permanent.
nameserversstring[]
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_urlstring
Link to the DNS host console.
domain_connectobject
One-click DNS setup (Domain Connect), from the last discovery. See Get Domain Connect Setup.
verified_atstring (date-time)
When the domain became VERIFIED.
last_checked_atstring (date-time)
When the DNS records were last checked.

DomainConnect

supportedbooleanRequired
The zone DNS provider supports Domain Connect and has the MachineMail template.
provider_namestring
Display name of the DNS provider.
apply_urlstring
Signed link that opens the provider with the outstanding records prefilled. Absent when nothing is left to add.
provider_idstring
Domain Connect provider ID.
url_sync_uxstring
Base URL of the provider synchronous flow.
widthinteger
Suggested popup width, in pixels.
heightinteger
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_atstring (date-time)Required
When discovery last ran.

DomainItem

pod_idstringRequired
ID of the pod the domain belongs to.
domain_idstringRequired
ID of the domain.
domainstringRequired
The domain name (for example example.com), lowercased.
feedback_enabledbooleanRequired
Stored as given. MachineMail does not send bounce and complaint notifications to inboxes; use the message.bounced and message.complained events.
inbound_enabledbooleanRequired
Receive email for this domain. false makes it send-only: the inbound MX record is not required.
subdomains_enabledbooleanRequired
Always false: inboxes on subdomains are not supported.
tracking_enabledbooleanRequired
Always false: open tracking is not supported.
client_idstring
Client ID given at creation (idempotency key).
updated_atstring (date-time)Required
Time at which the domain was last updated.
created_atstring (date-time)Required
Time at which the domain was created.
status"NOT_STARTED" | "PENDING" | "INVALID" | "FAILED" | "VERIFYING" | "VERIFIED"Required
Verification status, as on Domain.
reasonstring
Why the domain is not verified yet, as on Domain.
recordsVerificationRecord[]Required
DNS records to publish, as on Domain.
organization_idstringRequired
ID of the organization.
catch_allbooleanRequired
Mail to any address at the domain without an inbox creates one (created_by: catch_all).
catch_all_ttl_secondsinteger
TTL of inboxes created by catch-all; absent means they are permanent.
nameserversstring[]
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_urlstring
Link to the DNS host console.
domain_connectobject
One-click DNS setup (Domain Connect), from the last discovery. See Get Domain Connect Setup.
verified_atstring (date-time)
When the domain became VERIFIED.
last_checked_atstring (date-time)
When the DNS records were last checked.

Draft

inbox_idstringRequired
ID of the inbox.
draft_idstringRequired
ID of the draft.
labelsstring[]Required
Labels of the draft. The sent message gets them.
tostring[]
Recipient addresses.
ccstring[]
CC addresses.
bccstring[]
BCC addresses.
subjectstring
Subject of the draft.
previewstring
Text preview of the draft.
attachmentsAttachment[]
Attachments of the draft. size is 0 for attachments given by url until the draft is sent (the URL is fetched then).
in_reply_tostring
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_atstring (date-time)
Time at which the draft is sent automatically.
updated_atstring (date-time)Required
Time at which the draft was last updated.
client_idstring
Client ID given at creation (idempotency key).
reply_tostring[]
Reply-to addresses.
textstring
Plain text body.
htmlstring
HTML body.
referencesstring[]
Message IDs the draft references (set from in_reply_to).
created_atstring (date-time)Required
Time at which the draft was created.
pod_idstringRequired
ID of the pod.

DraftItem

inbox_idstringRequired
ID of the inbox.
draft_idstringRequired
ID of the draft.
labelsstring[]Required
Labels of the draft. The sent message gets them.
tostring[]
Recipient addresses.
ccstring[]
CC addresses.
bccstring[]
BCC addresses.
subjectstring
Subject of the draft.
previewstring
Text preview of the draft.
attachmentsAttachment[]
Attachments of the draft. size is 0 for attachments given by url until the draft is sent (the URL is fetched then).
in_reply_tostring
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_atstring (date-time)
Time at which the draft is sent automatically.
updated_atstring (date-time)Required
Time at which the draft was last updated.
client_idstring
Client ID given at creation.
reply_tostring[]
Reply-to addresses.
textstring
Plain text body.
htmlstring
HTML body.
referencesstring[]
Message IDs the draft references.
created_atstring (date-time)Required
Time at which the draft was created.
pod_idstringRequired
ID of the pod.

EmailCodeStartRequest

emailstring
Address to send the code to. Optional with invitation_token (the code goes to the invited address).
nextstring
Same-origin path to land on after sign-in, for example /cli?code=ABCD-EFGH. Anything else is ignored. Default /app.
invitation_tokenstring
An invitation token (from /invite/{token}): signing in accepts the invitation.

EmailCodeStartResponse

oktrueRequired
redirect_tostring
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.
dev_codestring
Development only (noop transport or MACHINEMAIL_DEV_MAGIC_LINK=true): the code itself.

EmailCodeVerifyRequest

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

event_idstringRequired
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" | "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_idstringRequired
ID of the organization.
pod_idstring
ID of the pod. Absent for organization-level events.
inbox_idstring
ID of the inbox. Absent for events without an inbox (for example domain.verified).
dataRecord<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.
timestampstring (date-time)Required
When the event happened (same as created_at).
created_atstring (date-time)Required
When the event was stored.

FirstKeyResponse

api_keyOneTimeApiKeyRequired
An API key with its plaintext secret, returned once.

HealthResponse

status"ok"Required

Identity

Identity and scope of the credential.

scope_type"organization" | "pod" | "inbox"Required
The scope tier the credential is bound to.
scope_idstringRequired
ID of the most specific scope: inbox_id for an inbox credential, pod_id for a pod credential, otherwise organization_id.
organization_idstringRequired
ID of the organization.
pod_idstring
ID of the pod the credential is scoped to. Present when scope_type is pod, and for inbox credentials created under a pod.
inbox_idstring
ID of the inbox the credential is scoped to. Present when scope_type is inbox.
api_key_idstring
ID of the API key used. Absent for dashboard sessions and agent access tokens.
userobject
The signed-in user, for a dashboard session.

InboundRawResponse

countintegerRequired
Number of messages stored (one per recipient inbox that accepted it).
messagesMessage[]Required
The stored messages, marked received_via: "raw".
errorsobject[]
Recipients that could not be delivered to, when there were several and at least one succeeded.

Inbox

pod_idstringRequired
ID of the pod the inbox belongs to.
inbox_idstringRequired
ID of the inbox: its email address, as in AgentMail (inbox_id == email).
emailstringRequired
Email address of the inbox.
display_namestring
Display name: Display Name <username@domain.com>.
client_idstring
Client ID given at creation (idempotency key).
status"active" | "paused"Required
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.
metadataRecord<string, string | number | boolean>
Custom key-value pairs attached to the inbox.
updated_atstring (date-time)Required
Time at which the inbox was last updated.
created_atstring (date-time)Required
Time at which the inbox was created.
organization_idstringRequired
ID of the organization.
ephemeralbooleanRequired
Whether the inbox expires (see ttl_seconds).
ttl_secondsinteger
TTL of an ephemeral inbox. Each inbound message pushes expires_at to now + ttl_seconds.
expires_atstring (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

availablebooleanRequired
emailstringRequired
The address that was checked (lowercased).
reason"invalid_username" | "domain_not_found" | "taken"
Why the address is not available.
messagestring
Human-readable reason.

Invitation

An invitation to join the organization.

invitation_idstringRequired
ID of the invitation.
organization_idstringRequired
ID of the organization the invitee joins.
emailstringRequired
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_idstring
ID of the member who sent it, when known.
expires_atstring (date-time)Required
When the invitation stops working (7 days after it was sent).
created_atstring (date-time)Required
When the invitation was sent.
dev_linkstring
Development only (local sign-in with the noop transport or MACHINEMAIL_DEV_MAGIC_LINK=true): the sign-in link that accepts the invitation.

InvitationPreviewResponse

What an invitation link is for, before signing in.

organization_namestringRequired
The organization the invitation is to.
emailstringRequired
The invited address, masked (a••@example.com).
state"pending" | "accepted" | "expired" | "revoked"Required
Only a pending invitation can be accepted.
expires_atstring (date-time)Required
When the invitation expires.

JsonRpcError

JSON-RPC 2.0 error response.

jsonrpc"2.0"Required
errorobjectRequired
idstring | number | nullRequired

JsonWebKeySet

RFC 7517 JWK Set.

keysRecord<string, unknown>[]Required

ListAgentRegistrationsResponse

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

ListApiKeysResponse

countintegerRequired
Number of items returned.
limitintegerRequired
Page size used.
next_page_tokenstring
Page token for pagination. Absent on the last page.
api_keysBearerApiKey[]Required
Keys in the route scope that are not revoked, ordered by created_at, newest first unless ascending is set.

ListDeliveriesResponse

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

ListDomainsResponse

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

ListDraftsResponse

countintegerRequired
Number of items returned.
limitinteger
Maximum number of items per page. Default 50, maximum 500; larger values are capped.
next_page_tokenstring
Page token for pagination. Absent on the last page.
draftsDraftItem[]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.

entrystringRequired
Email address or domain (lowercased).
organization_idstringRequired
ID of the organization.
pod_idstring
ID of the pod, for pod-scoped entries.
inbox_idstring
ID of the inbox, for inbox-scoped entries.
reasonstring
Reason given when the entry was added.
direction"send" | "receive" | "reply"Required
receive: who may send to you (inbound mail from a blocked sender is labeled BLOCKED). send: who you may send to (a blocked recipient is a 403). reply entries are stored and listed but not applied to any mail yet.
list_type"allow" | "block"Required
block refuses matching addresses. allow makes the list exclusive: once it has an entry, only matching addresses pass.
entry_type"email" | "domain"Required
Whether the entry is an email address or a domain.
read_onlybooleanRequired
Always false: every entry can be deleted through the API.
created_atstring (date-time)Required
Time at which the entry was created.

ListEventsResponse

countintegerRequired
Number of items returned.
limitinteger
Maximum number of items per page. Default 50, maximum 500; larger values are capped.
next_page_tokenstring
Page token for pagination. Absent on the last page.
eventsEvent[]Required
Newest first; oldest first when after is set or ascending is true.

ListInboxesResponse

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

ListInvitationsResponse

countintegerRequired
Number of items returned.
limitinteger
Maximum number of items per page. Default 50, maximum 500; larger values are capped.
next_page_tokenstring
Page token for pagination. Absent on the last page.
invitationsInvitation[]Required
Pending invitations, newest first.

ListListEntriesResponse

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

ListMembersResponse

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

ListMessagesResponse

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

ListOAuthGrantsResponse

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

ListPodsResponse

countintegerRequired
Number of items returned.
limitinteger
Maximum number of items per page. Default 50, maximum 500; larger values are capped.
next_page_tokenstring
Page token for pagination. Absent on the last page.
podsPod[]Required
Ordered by created_at, newest first unless ascending is set. A pod credential sees only its pod.

ListSessionOrganizationsResponse

organizationsMembershipOrganization[]Required
Every organization the person belongs to, by name.

ListSuppressionsResponse

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

ListThreadsResponse

countintegerRequired
Number of items returned.
limitinteger
Maximum number of items per page. Default 50, maximum 500; larger values are capped.
next_page_tokenstring
Page token for pagination. Absent on the last page.
threadsThreadItem[]Required
Ordered by timestamp, newest first unless ascending is set.
truncatedtrue
Present when q matched more than 500 messages: only the threads of the newest 500 matching messages were considered.

ListWebhooksResponse

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

LoginRequest

emailstringRequired
passwordstringRequired

MagicLinkRequest

emailstringRequired
Address to send the sign-in link to.
org_namestring
Organization name, used only when this is the address’s first sign-in.
nextstring
Same-origin path to land on after sign-in, for example /claim?user_code=123456. Anything else is ignored. Default /app.
organization_namestring
Alias of org_name.
organizationNamestringDeprecated
Alias of org_name.

MagicLinkResponse

oktrueRequired
dev_linkstring
Development only (noop transport or MACHINEMAIL_DEV_MAGIC_LINK=true): the sign-in link itself.

McpDescription

How to connect to the remote MCP server.

namestringRequired
versionstringRequired
transport"streamable-http"Required
urlstringRequired
The canonical MCP endpoint: MACHINEMAIL_MCP_URL (https://mcp.machinemail.dev/mcp), default <PUBLIC_URL>/mcp. <PUBLIC_URL>/mcp also works (legacy alias).
authenticationobjectRequired
docsstringRequired

MembershipOrganization

An organization the signed-in person belongs to.

organization_idstringRequired
ID of the organization.
namestringRequired
Name of the organization.
slugstringRequired
URL-safe name of the organization.
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.
currentbooleanRequired
The session is signed in to this organization.

Message

inbox_idstringRequired
ID of the inbox.
thread_idstringRequired
ID of the thread.
message_idstringRequired
ID of the message.
labelsstring[]Required
Labels of the message.
timestampstring (date-time)Required
Time at which the message was sent or received.
fromstringRequired
Address of the sender. In format username@domain.com or Display Name <username@domain.com>.
tostring[]Required
Addresses of the recipients. In format username@domain.com or Display Name <username@domain.com>.
ccstring[]
Addresses of the CC recipients. In format username@domain.com or Display Name <username@domain.com>.
bccstring[]
Addresses of the BCC recipients. In format username@domain.com or Display Name <username@domain.com>.
subjectstring
Subject of the message.
previewstring
Text preview of the message.
attachmentsAttachment[]
Attachments of the message.
in_reply_tostring
ID of the message being replied to.
referencesstring[]
IDs of previous messages in the thread.
headersRecord<string, string>
Headers of the message.
sizeintegerRequired
Size of the message in bytes.
updated_atstring (date-time)Required
Time at which the message was last updated.
created_atstring (date-time)Required
Time at which the message was created.
pod_idstringRequired
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_tostring[]
Reply-to addresses. In format username@domain.com or Display Name <username@domain.com>.
textstring
Plain text body. Untrusted: agents should read trust.content.text or extracted_text.
htmlstring
HTML body. Untrusted.
extracted_textstring
New text content, without quoted replies.
extracted_htmlstring
New HTML content, without quoted replies.
received_via"raw"
raw when the message was injected with POST /inbound/raw (authentication not verified).
trustTrustReport
Trust report of an inbound message.

MessageItem

A message without its bodies, as in lists.

inbox_idstringRequired
ID of the inbox.
thread_idstringRequired
ID of the thread.
message_idstringRequired
ID of the message.
labelsstring[]Required
Labels of the message.
timestampstring (date-time)Required
Time at which the message was sent or received.
fromstringRequired
Address of the sender. In format username@domain.com or Display Name <username@domain.com>.
tostring[]Required
Addresses of the recipients. In format username@domain.com or Display Name <username@domain.com>.
ccstring[]
Addresses of the CC recipients. In format username@domain.com or Display Name <username@domain.com>.
bccstring[]
Addresses of the BCC recipients. In format username@domain.com or Display Name <username@domain.com>.
subjectstring
Subject of the message.
previewstring
Text preview of the message.
attachmentsAttachment[]
Attachments of the message.
in_reply_tostring
ID of the message being replied to.
referencesstring[]
IDs of previous messages in the thread.
headersRecord<string, string>
Headers of the message.
sizeintegerRequired
Size of the message in bytes.
updated_atstring (date-time)Required
Time at which the message was last updated.
created_atstring (date-time)Required
Time at which the message was created.
pod_idstringRequired
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

timestampstring (date-time)Required
Start of the bucket.
countintegerRequired
Number of events in the bucket.

OAuthApproveRequest

request_idstringRequired
pod_idstring
Limit the grant to one pod of the organization. Default: the whole organization.
inbox_idstring
Limit the grant to one inbox (and its pod).

OAuthAuthorizationRequest

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

request_idstringRequired
clientOAuthClientInfoRequired
redirect_uristringRequired
Where the response goes.
redirect_hoststringRequired
Host (or scheme, for an app link) of redirect_uri, for the human to check.
redirect_loopbackbooleanRequired
The response goes to a program on this computer (http://127.0.0.1, localhost).
resourcestringRequired
What the token will be good for: the MCP server (https://mcp.machinemail.dev/mcp, or the legacy <issuer>/mcp) or <issuer>/ (the REST API and MCP).
scopesScopeDescription[]Required
What the client asked for.
created_atstring (date-time)Required
expires_atstring (date-time)Required
When the request expires (10 minutes after it was made).

OAuthClientInfo

client_idstringRequired
client_namestring | nullRequired
Self-reported by the client.
client_uristring | nullRequired
Self-reported; https only.
logo_uristring | 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.
hoststring | nullRequired
metadata_document: the host that serves the document (for example claude.ai).

OAuthDecision

status"approved" | "denied"Required
redirect_tostringRequired
Send the browser here: redirect_uri with code (or error=access_denied), state and iss.

OAuthDenyRequest

request_idstringRequired

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.

errorstringRequired
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_descriptionstringRequired
messagestringRequired
Same text as error_description.
registration_idstring
interaction_required only.
agent_idstring
interaction_required only.
registration_type"anonymous" | "service_auth" | "identity_assertion"
interaction_required only.
claim_urlstring
interaction_required only.
claim_tokenstring
interaction_required only.
claim_token_expiresstring (date-time)
interaction_required 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")[]
interaction_required only.
claimobject
interaction_required only.
max_ageinteger
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.

grant_idstringRequired
ID of the grant (oag_...).
client_idstringRequired
client_namestring | nullRequired
Self-reported by the client at registration.
client_uristring | nullRequired
logo_uristring | nullRequired
registration"dynamic" | "metadata_document"Required
user_idstringRequired
Who approved it.
user_emailstring | 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
resourcestringRequired
Audience of its access tokens.
pod_idstring | nullRequired
Set when the grant is limited to one pod.
inbox_idstring | nullRequired
Set when the grant is limited to one inbox.
created_atstring (date-time)Required
last_used_atstring (date-time) | nullRequired
Last token refresh or API call (updated at most once a minute).
expires_atstring (date-time)Required
When the current refresh token expires unless it is used (30 days after the last refresh).

OkResponse

Acknowledgement.

oktrueRequired

OneTimeApiKey

An API key with its plaintext secret, returned once.

api_key_idstringRequired
ID of the API key.
api_keystringRequired
Plaintext secret (mm_live_...). Shown once.
prefixstringRequired
First characters of the key, shown in listings.
namestringRequired
Name of the key.
created_atstring (date-time)Required
When the key was created.

Organization

The organization of the credential. There are no inbox or domain quotas to report (inbox_limit, domain_limit) and no billing fields.

organization_idstringRequired
ID of the organization.
namestringRequired
Name of the organization.
slugstringRequired
URL-safe name of the organization.
plan"free" | "pro" | "enterprise"Required
Plan of the organization.
inbox_countintegerRequired
Number of inboxes in the credential scope.
domain_countintegerRequired
Number of domains in the organization.
usageobject
Usage. Always present on GET /v0/organizations and PATCH /v0/organizations.
shared_domainstring
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.
updated_atstring (date-time)Required
Time at which the organization was last updated.
created_atstring (date-time)Required
Time at which the organization was created.

PendingOrganizationRequest

organization_idstringRequired
One of the organizations from GET /auth/pending.

PendingSignInResponse

The sign-in in progress in this browser.

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.
emailstring
The address signing in, when known.
organizationsobject[]
For organization: the organizations to pick from.
invitationbooleanRequired
Signing in accepts an invitation.

PendingVerifyRequest

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

Pod

pod_idstringRequired
ID of the pod.
organization_idstringRequired
ID of the organization.
namestringRequired
Name of the pod.
is_defaultbooleanRequired
Whether this is the default pod, where inboxes go when no pod is given. It cannot be deleted.
client_idstring
Client ID given at creation (idempotency key).
updated_atstring (date-time)Required
Time at which the pod was last updated.
created_atstring (date-time)Required
Time at which the pod was created.

ProtectedResourceMetadata

RFC 9728 OAuth Protected Resource Metadata.

resourcestringRequired
The protected resource: <issuer>/ (the REST API and MCP), or <issuer>/<path> 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, <issuer>/mcp is the legacy MCP alias.
authorization_serversstring[]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_supportedstring[]Required
header.
resource_namestringRequired
resource_logo_uristringRequired
resource_documentationstringRequired
The /auth.md document, or the MCP guide for <issuer>/mcp.

RatePoint

timestampstring (date-time)Required
End of the window the point covers; the window is the window seconds before it.
ratenumber
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.
sentintegerRequired
Messages sent in the window.

ReadyResponse

status"ready" | "unavailable"Required
ready when storage answers; the HTTP status is then 200, otherwise 503.
checksobjectRequired

Recipient

addressstringRequired
Recipient address.
statusstringRequired
bounced or complained.

Reject

inbox_idstringRequired
ID of the inbox.
thread_idnullRequired
Always null: nothing was stored.
message_idnullRequired
Always null: nothing was stored.
timestampstring (date-time)Required
When it happened.
reason"inbox_paused"Required
Why the message was rejected. inbox_paused: the inbox is paused.
fromstringRequired
Sender of the rejected message.
subjectstring
Subject of the rejected message.

ReplyAllMessageRequest

labelsstring | string[]
Labels of the message. SENT is always added.
reply_tostring | string[]
Reply-to address or addresses.
textstring
Plain text body.
htmlstring
HTML body.
attachmentsSendAttachment[]
Attachments to include.
headersRecord<string, string>
Headers to include. In-Reply-To and References also thread the message.
tostring | string[]
More recipients, added to the sender and recipients of the original.
ccstring | string[]
More CC recipients, added to the CC recipients of the original.
bccstring | string[]
BCC recipient address or addresses.
subjectstring
Subject of the reply. Defaults to the original subject with Re: in front.

ReplyToMessageRequest

labelsstring | string[]
Labels of the message. SENT is always added.
reply_tostring | string[]
Reply-to address or addresses.
tostring | string[]
Recipient address or addresses. Defaults to the sender of the original (its reply-to addresses if any); for an outbound original, its recipients.
ccstring | string[]
CC recipient address or addresses.
bccstring | string[]
BCC recipient address or addresses.
reply_allboolean
true replies to all recipients of the original, as Reply All Message does; to and cc are then added to them.
textstring
Plain text body.
htmlstring
HTML body.
attachmentsSendAttachment[]
Attachments to include.
headersRecord<string, string>
Headers to include. In-Reply-To and References also thread the message.
subjectstring
Subject of the reply. Defaults to the original subject with Re: in front.

ResendWebhookResult

processedintegerRequired
Recipients stored (email.received) or feedback events recorded.
errorsstring[]
Per-recipient failures.

RevokeRequest

tokenstringRequired
An access token, a refresh token or an identity assertion.
token_type_hintstring
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_idstring
Refresh and access tokens of an app: when given, must be the client the token was issued to, or nothing is revoked.
client_secretstring
A confidential client authenticates as at the token endpoint (client_secret_post, or HTTP Basic).

ScopeDescription

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

SearchInboxesResponse

countintegerRequired
Number of items returned.
limitinteger
Maximum number of items per page. Default 50, maximum 500; larger values are capped.
next_page_tokenstring
Page token for pagination. Absent on the last page.
inboxesInbox[]Required
Matching inboxes, newest first.
truncatedtrue
Present when the organization has more than 500 inboxes in scope: only the newest 500 were searched.

SearchMessagesResponse

countintegerRequired
Number of items returned.
limitinteger
Maximum number of items per page. Default 50, maximum 500; larger values are capped.
next_page_tokenstring
Page token for pagination. Absent on the last page.
messagesMessageItem[]Required
Matching messages, newest first unless ascending is set.

SearchThreadsResponse

countintegerRequired
Number of items returned.
limitinteger
Maximum number of items per page. Default 50, maximum 500; larger values are capped.
next_page_tokenstring
Page token for pagination. Absent on the last page.
threadsThreadItem[]Required
Matching threads, ordered by timestamp, newest first unless ascending is set.
truncatedtrue
Present when q matched more than 500 messages: only the threads of the newest 500 matching messages were considered.

Send

inbox_idstringRequired
ID of the inbox.
thread_idstringRequired
ID of the thread.
message_idstringRequired
ID of the message.
timestampstring (date-time)Required
When it happened.
recipientsstring[]Required
Every recipient (to, cc and bcc).

SendAttachment

Provide either content or url for each attachment.

filenamestring
Filename of the attachment. Defaults to the last segment of url.
content_typestring
Content type of the attachment. Defaults to the Content-Type of the url response.
content_disposition"inline" | "attachment"
Content disposition of the attachment.
content_idstring
Content ID, for inline images referenced as cid: in the HTML body.
contentstring
Base64 encoded content of the attachment.
urlstring
URL the API downloads the attachment from: public http(s) only, no redirects, at most 25 MB, 20 second timeout.

SendMessageRequest

labelsstring | string[]
Labels of the message. SENT is always added.
reply_tostring | string[]
Reply-to address or addresses.
tostring | string[]
Recipient address or addresses.
ccstring | string[]
CC recipient address or addresses.
bccstring | string[]
BCC recipient address or addresses.
subjectstring
Subject of the message.
textstring
Plain text body.
htmlstring
HTML body.
attachmentsSendAttachment[]
Attachments to include.
headersRecord<string, string>
Headers to include. In-Reply-To and References also thread the message.

SendMessageResponse

message_idstringRequired
ID of the message.
thread_idstringRequired
ID of the thread.
timestampstring (date-time)Required
When the message was sent.

SessionResponse

The signed-in user and their organization.

userUserRequired
A person who signs in to the dashboard.
organizationOrganizationRequired
The organization of the credential. There are no inbox or domain quotas to report (inbox_limit, domain_limit) and no billing fields.

SetError

RFC 8935 SET delivery error.

errstringRequired
invalid_request, invalid_issuer, invalid_key or invalid_audience.
descriptionstringRequired

SignInStepResponse

The result of a sign-in step.

oktrueRequired
signed_inbooleanRequired
true: the mm_session cookie is set. false: another step comes first (organization picker, email verification, SSO).
redirect_tostringRequired
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=<code>.

SignupRequest

emailstringRequired
passwordstringRequired
At least 8 characters.
namestring
Display name of the user.
org_namestring
Organization name.
organization_namestring
Alias of org_name.
organizationNamestringDeprecated
Alias of org_name.

SignupResponse

The new user, their organization and the first organization API key (shown once).

userUserRequired
A person who signs in to the dashboard.
organizationOrganizationRequired
The organization of the credential. There are no inbox or domain quotas to report (inbox_limit, domain_limit) and no billing fields.
api_keyOneTimeApiKeyRequired
An API key with its plaintext secret, returned once.

Suppression

An address MachineMail will not send to. Suppressions apply to the whole organization.

emailstringRequired
The suppressed address (lowercased).
organization_idstringRequired
ID of the organization.
reason"bounce" | "complaint" | "manual"Required
bounce: a permanent bounce. complaint: the recipient reported spam; only MachineMail support can remove it. manual: added with POST /v0/suppressions.
detailstring
Free text: the bounce diagnostic, or the note given when the address was added manually.
source_message_idstring
Message whose bounce or complaint caused the suppression.
created_atstring (date-time)Required
When the address was suppressed.

SwitchOrganizationRequest

organization_idstringRequired
ID of an organization the person belongs to.

Thread

inbox_idstringRequired
ID of the inbox.
thread_idstringRequired
ID of the thread.
labelsstring[]Required
Labels of the thread: the union of the labels of its messages.
timestampstring (date-time)Required
Timestamp of the last sent or received message.
received_timestampstring (date-time)
Timestamp of the last received message.
sent_timestampstring (date-time)
Timestamp of the last sent message.
sendersstring[]Required
Senders in the thread. In format username@domain.com.
recipientsstring[]Required
Recipients (to and cc) in the thread. In format username@domain.com.
subjectstring
Subject of the thread.
previewstring
Text preview of the last message in the thread.
attachmentsAttachment[]
Attachments in the thread.
last_message_idstringRequired
ID of the last message in the thread.
message_countintegerRequired
Number of messages in the thread.
sizeintegerRequired
Size of the thread in bytes.
updated_atstring (date-time)Required
Time at which the thread was last updated.
created_atstring (date-time)Required
Time at which the thread was created.
pod_idstringRequired
ID of the pod.
countintegerRequired
Number of messages in this page.
limitinteger
Maximum number of messages requested for this page.
next_page_tokenstring
Token for the next, older page of messages. Absent when this page completes the thread.
messagesMessage[]Required
Messages in this page, oldest first. The first page has the newest messages; follow next_page_token for older ones.

ThreadItem

inbox_idstringRequired
ID of the inbox.
thread_idstringRequired
ID of the thread.
labelsstring[]Required
Labels of the thread: the union of the labels of its messages.
timestampstring (date-time)Required
Timestamp of the last sent or received message.
received_timestampstring (date-time)
Timestamp of the last received message.
sent_timestampstring (date-time)
Timestamp of the last sent message.
sendersstring[]Required
Senders in the thread. In format username@domain.com.
recipientsstring[]Required
Recipients (to and cc) in the thread. In format username@domain.com.
subjectstring
Subject of the thread.
previewstring
Text preview of the last message in the thread.
attachmentsAttachment[]
Attachments in the thread.
last_message_idstringRequired
ID of the last message in the thread.
message_countintegerRequired
Number of messages in the thread.
sizeintegerRequired
Size of the thread in bytes.
updated_atstring (date-time)Required
Time at which the thread was last updated.
created_atstring (date-time)Required
Time at which the thread was created.
pod_idstringRequired
ID of the pod.

TokenRequest

grant_typestringRequired
authorization_code (with PKCE) and refresh_token for apps and MCP clients; urn:ietf:params:oauth:grant-type:device_code for mm login; urn:ietf:params:oauth:grant-type:jwt-bearer (RFC 7523) exchanges an assertion; urn:workos:agent-auth:grant-type:claim polls with a claim_token. Other values: unsupported_grant_type.
codestring
authorization_code: the code from the authorization response. Single use; expires after 2 minutes.
redirect_uristring
authorization_code: the redirect_uri of the authorization request, when it had one.
code_verifierstring
authorization_code: the PKCE code verifier (43 to 128 characters).
refresh_tokenstring
refresh_token: the current refresh token. Each use returns a new one; presenting a replaced one within 60 seconds of its replacement returns the current one, later it revokes the whole grant.
scopestring
refresh_token, optional: narrow the new access token to these scopes of the grant.
device_codestring
device_code: the device_code from /auth/cli/device/code.
assertionstring
jwt-bearer grant: the identity_assertion.
client_idstring
authorization_code and refresh_token: the client the code or token was issued to (invalid_grant otherwise); may instead come from an HTTP Basic Authorization header (client_secret_basic), or be left out (taken from the code or token). device_code: required. jwt-bearer, optional: the registration id.
client_secretstring
Confidential clients using client_secret_post (registered with a secret). Alternatively send Authorization: Basic base64(urlencode(client_id):urlencode(client_secret)) (client_secret_basic), not both. A missing or wrong secret: 401 invalid_client. Public clients need none; one they send is ignored.
resourcestring
RFC 8707. authorization_code and refresh_token: must be the resource of the authorization request (invalid_target otherwise). jwt-bearer, optional audience pin: must be <issuer>/.
claim_tokenstring
Claim grant: the claim_token from registration.

TokenResponse

auth.md grants issue no refresh_token (exchange the identity_assertion again); the authorization code and refresh grants do.

access_tokenstringRequired
JWT (at+jwt) to send as Authorization: Bearer. Tokens from the authorization code grant are audience-bound: aud the MCP server (https://mcp.machinemail.dev/mcp, or the legacy <issuer>/mcp) works on the MCP endpoint only (either URL), <issuer>/ on /v0 and the MCP endpoint. auth.md tokens work on both.
token_type"Bearer"Required
expires_inintegerRequired
Lifetime of the access token in seconds.
scopestringRequired
Space-separated Scope values.
refresh_tokenstring
authorization_code and refresh_token grants: the new refresh token (rotated on every use).
identity_assertionstring
Claim grant only: the post-claim identity assertion.
assertion_expiresstring (date-time)

TrustReport

Trust report of an inbound message. Message content is untrusted: feed content.text to an LLM rather than the message text or html.

level"verified" | "known" | "unknown" | "suspicious" | "quarantined"Required
Overall verdict, safest first. quarantined messages are labelled QUARANTINE and hidden from lists unless asked for.
scorenumberRequired
0 to 1, higher is safer. Ranks messages within a level. (minimum 0, maximum 1)
authenticationobjectRequired
senderobjectRequired
contentobjectRequired
linksobject[]Required
attachmentsobject[]Required
classificationobjectRequired
reasonsstring[]Required
Human-readable reasons for the verdict.
computed_atstring (date-time)Required
When the report was computed.

UpdateApiKeyRequest

Fields you omit are unchanged. permissions replaces the permission object in full. Scope and expiry cannot be changed.

namestring
New name. A blank name is ignored.
permissionsobject
New permissions; replaces the permission object in full.

UpdateDomainRequest

feedback_enabledboolean
Stored and returned; has no effect.
inbound_enabledboolean
Receive email for this domain. false makes the inbound MX record optional and re-evaluates the status.
catch_allboolean
Create an inbox for any address at the domain that receives mail.
catch_all_ttl_secondsinteger | null
TTL of inboxes created by catch-all from now on. null makes them permanent.

UpdateDraftRequest

reply_tostring | string[] | null
Reply-to addresses. null clears them.
tostring | string[] | null
Recipient addresses. null clears them.
ccstring | string[] | null
CC addresses. null clears them.
bccstring | string[] | null
BCC addresses. null clears them.
subjectstring | null
Subject. null clears it.
textstring | null
Plain text body. null clears it.
htmlstring | null
HTML body. null clears it.
add_attachmentsSendAttachment[]
Attachments to add. Each needs content or url.
remove_attachmentsstring[]
IDs of attachments to remove. Unknown IDs are ignored.
add_labelsstring[]
Labels to add.
remove_labelsstring[]
Labels to remove (applied after add_labels).
send_atstring (date-time) | null
Schedule (or reschedule) the draft. null unschedules it.

UpdateInboxRequest

display_namestring
Display name: Display Name <username@domain.com>.
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 | null>) | null
Merged into the existing metadata: keys you send are added or overwritten, keys set to null are removed, other keys are kept. null clears all metadata.
ttl_secondsinteger | null
Make the inbox ephemeral with this TTL (expires_at restarts from now), or null to make it permanent.
ephemeralboolean
false makes the inbox permanent (same as ttl_seconds: null). true alone has no effect; send ttl_seconds.

UpdateMemberRequest

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.

UpdateMessageRequest

add_labelsstring | string[]
Label or labels to add.
remove_labelsstring | string[]
Label or labels to remove.

UpdateMessageResponse

message_idstringRequired
ID of the message.
labelsstring[]Required
Labels of the message after the update.

UpdateOrganizationRequest

namestring
New name. Must not be blank.

UpdatePodRequest

namestring
New name. Must not be blank.

UpdateThreadRequest

add_labelsstring | string[]
Label or labels to add to every message in the thread.
remove_labelsstring | string[]
Label or labels to remove from every message in the thread. Applied after add_labels.

UpdateWebhookRequest

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")[]
Replaces the subscribed event types in full (not a merge). An empty array subscribes to every event type except domain.updated, which is sent only when listed. Omit it to keep the types.
enabledboolean
false disables the webhook: no new deliveries are queued (deliveries already queued are still attempted). true enables it again. Events that occurred while it was disabled are not delivered later.
add_inbox_idsstring[]
Inboxes to add to inbox_ids.
remove_inbox_idsstring[]
Inboxes to remove from inbox_ids.
add_pod_idsstring[]
Pods to add to pod_ids.
remove_pod_idsstring[]
Pods to remove from pod_ids.
urlstring
New endpoint URL: a public http(s) URL.

UsagePoint

timestampstring (date-time)Required
Time of the value (end).
valueintegerRequired
Value of the usage metric now.

User

A person who signs in to the dashboard.

user_idstringRequired
ID of the user.
emailstringRequired
Email address the user signs in with.
namestring | null
Display name, when set.
organization_idstringRequired
ID of the organization this record is about: the session’s active organization, or the organization listed.
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.
created_atstring (date-time)Required
When the user was created.

VerificationRecord

type"TXT" | "CNAME" | "MX"Required
namestringRequired
Name (host) of the record.
valuestringRequired
Value of the record.
status"MISSING" | "INVALID" | "VALID"Required
MISSING: not published yet. INVALID: published with the wrong value.
priorityinteger
Priority of an MX record.
reasonstring
Why an INVALID record is invalid: Found: <values seen>.
purpose"inbound" | "spf" | "dkim" | "dmarc" | "provider"Required
What the record is for. provider records come from the sending provider.
requiredbooleanRequired
Whether the record must be valid for the domain to verify. The inbound MX record is not required when inbound_enabled is false.

Webhook

webhook_idstringRequired
ID of the webhook.
urlstringRequired
URL of the webhook endpoint.
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")[]Required
Event types the webhook receives. Empty: every event type except domain.updated, which is sent only when listed.
pod_idsstring[]
Only events of these pods. Absent: every pod in scope.
inbox_idsstring[]
Only events of these inboxes. Absent: every inbox in scope.
pod_idstring
Set when the webhook was created with a pod-scoped credential (or under /v0/pods/{pod_id}): it never receives events outside that pod.
inbox_idstring
Set when the webhook was created with an inbox-scoped credential (or under /v0/inboxes/{inbox_id}): it only receives events of that inbox.
secretstringRequired
Signing secret (whsec_...) for X-MachineMail-Signature. Returned on every read.
enabledbooleanRequired
Whether new events are delivered. Webhooks are never disabled automatically.
updated_atstring (date-time)Required
Time at which the webhook was last updated.
created_atstring (date-time)Required
Time at which the webhook was created.
client_idstring
Client ID given at creation (idempotency key).
status"active" | "disabled"Required
active or disabled; mirrors enabled.

WebhookDelivery

delivery_idstringRequired
ID of the delivery (X-MachineMail-Delivery-Id).
webhook_idstringRequired
ID of the webhook.
event_idstringRequired
ID of the event (X-MachineMail-Event-Id).
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"Required
Type of event. AgentMail has no message.received.quarantined, domain.updated, inbox.created, inbox.expired, draft.sent or webhook.test; MachineMail does not emit message.opened or calendar.event.*. domain.updated is sent whenever a DNS check changes the domain status or a record status (the change to VERIFIED also sends domain.verified); webhooks and WebSocket subscriptions receive it only when their event_types list it, while the SSE stream and the event log always include it.
attemptintegerRequired
Number of attempts so far.
status"pending" | "delivered" | "failed"Required
pending until a 2xx response (delivered), or failed when retries stop (5 days after the event) or the webhook or event was deleted.
response_statusinteger
HTTP status of the last attempt.
response_bodystring
First 1024 bytes of the last response body.
next_attempt_atstring (date-time)
When the next attempt is due, while pending.
last_errorstring
Error of the last failed attempt (HTTP 500, a network error).
delivered_atstring (date-time)
When the delivery succeeded.
created_atstring (date-time)Required
When the delivery was queued.
updated_atstring (date-time)Required
Last change to the delivery.

On this page

AgentIdentityRequestAgentIdentityResponseAgentRegistrationApiKeyPermissionsAttachmentAttachmentResponseAuthConfigResponseAuthorizationServerMetadataBatchGetMessagesRequestBatchGetMessagesResponseBatchUpdateMessagesRequestBatchUpdateMessagesResponseBearerApiKeyBounceClaimBlockClaimCompleteRequestClaimCompleteResponseClaimPreviewResponseClaimStartRequestClaimStartResponseCliDeviceAuthorizationCliDeviceCodeRequestCliDeviceCodeResponseCliDeviceDecisionCliDeviceDecisionRequestCliDeviceTokenRequestCliDeviceTokenResponseClientRegistrationRequestClientRegistrationResponseComplaintCreateApiKeyResponseCreateBearerApiKeyRequestCreateDomainRequestCreateDraftRequestCreateInboxRequestCreateInvitationRequestCreateListEntryRequestCreatePodRequestCreateSessionOrganizationRequestCreateSuppressionRequestCreateWebhookRequestDeliveryDomainDomainConnectDomainItemDraftDraftItemEmailCodeStartRequestEmailCodeStartResponseEmailCodeVerifyRequestEventFirstKeyResponseHealthResponseIdentityInboundRawResponseInboxInboxAvailabilityInvitationInvitationPreviewResponseJsonRpcErrorJsonWebKeySetListAgentRegistrationsResponseListApiKeysResponseListDeliveriesResponseListDomainsResponseListDraftsResponseListEntryListEventsResponseListInboxesResponseListInvitationsResponseListListEntriesResponseListMembersResponseListMessagesResponseListOAuthGrantsResponseListPodsResponseListSessionOrganizationsResponseListSuppressionsResponseListThreadsResponseListWebhooksResponseLoginRequestMagicLinkRequestMagicLinkResponseMcpDescriptionMembershipOrganizationMessageMessageItemMetricBucketOAuthApproveRequestOAuthAuthorizationRequestOAuthClientInfoOAuthDecisionOAuthDenyRequestOAuthErrorOAuthGrantOkResponseOneTimeApiKeyOrganizationPendingOrganizationRequestPendingSignInResponsePendingVerifyRequestPodProtectedResourceMetadataRatePointReadyResponseRecipientRejectReplyAllMessageRequestReplyToMessageRequestResendWebhookResultRevokeRequestScopeDescriptionSearchInboxesResponseSearchMessagesResponseSearchThreadsResponseSendSendAttachmentSendMessageRequestSendMessageResponseSessionResponseSetErrorSignInStepResponseSignupRequestSignupResponseSuppressionSwitchOrganizationRequestThreadThreadItemTokenRequestTokenResponseTrustReportUpdateApiKeyRequestUpdateDomainRequestUpdateDraftRequestUpdateInboxRequestUpdateMemberRequestUpdateMessageRequestUpdateMessageResponseUpdateOrganizationRequestUpdatePodRequestUpdateThreadRequestUpdateWebhookRequestUsagePointUserVerificationRecordWebhookWebhookDelivery
0% read