[Skip to content](/content/docs/reference/api/api-keys#nd-page/index.html) [Skip to content](/content/docs/reference/api/api-keys#nd-page/index.html) \[01/15\]List API Keys | Method | Path | Summary | | --- | --- | --- | | `GET` | `/v0/api-keys` | [List API Keys](/content/docs/reference/api/api-keys#list-api-keys/index.html) | | `POST` | `/v0/api-keys` | [Create API Key](/content/docs/reference/api/api-keys#create-api-key/index.html) | | `GET` | `/v0/api-keys/{api_key_id}` | [Get API Key](/content/docs/reference/api/api-keys#get-api-key/index.html) | | `PATCH` | `/v0/api-keys/{api_key_id}` | [Update API Key](/content/docs/reference/api/api-keys#update-api-key/index.html) | | `DELETE` | `/v0/api-keys/{api_key_id}` | [Delete API Key](/content/docs/reference/api/api-keys#delete-api-key/index.html) | | `GET` | `/v0/inboxes/{inbox_id}/api-keys` | [List API Keys in Inbox](/content/docs/reference/api/api-keys#list-api-keys-in-inbox/index.html) | | `POST` | `/v0/inboxes/{inbox_id}/api-keys` | [Create API Key in Inbox](/content/docs/reference/api/api-keys#create-api-key-in-inbox/index.html) | | `GET` | `/v0/inboxes/{inbox_id}/api-keys/{api_key_id}` | [Get API Key in Inbox](/content/docs/reference/api/api-keys#get-api-key-in-inbox/index.html) | | `PATCH` | `/v0/inboxes/{inbox_id}/api-keys/{api_key_id}` | [Update API Key in Inbox](/content/docs/reference/api/api-keys#update-api-key-in-inbox/index.html) | | `DELETE` | `/v0/inboxes/{inbox_id}/api-keys/{api_key_id}` | [Delete API Key in Inbox](/content/docs/reference/api/api-keys#delete-api-key-in-inbox/index.html) | | `GET` | `/v0/pods/{pod_id}/api-keys` | [List API Keys in Pod](/content/docs/reference/api/api-keys#list-api-keys-in-pod/index.html) | | `POST` | `/v0/pods/{pod_id}/api-keys` | [Create API Key in Pod](/content/docs/reference/api/api-keys#create-api-key-in-pod/index.html) | | `GET` | `/v0/pods/{pod_id}/api-keys/{api_key_id}` | [Get API Key in Pod](/content/docs/reference/api/api-keys#get-api-key-in-pod/index.html) | | `PATCH` | `/v0/pods/{pod_id}/api-keys/{api_key_id}` | [Update API Key in Pod](/content/docs/reference/api/api-keys#update-api-key-in-pod/index.html) | | `DELETE` | `/v0/pods/{pod_id}/api-keys/{api_key_id}` | [Delete API Key in Pod](/content/docs/reference/api/api-keys#delete-api-key-in-pod/index.html) | ## [List API Keys](/content/docs/reference/api/api-keys\#list-api-keys/index.html) http ``` GET /v0/api-keys ``` Keys that are not revoked. Under `/v0/pods/{pod_id}` or `/v0/inboxes/{inbox_id}`, only the keys scoped to that pod or inbox; a pod or inbox credential sees only keys in its own scope. **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `api_key_read`. #### [Query parameters](/content/docs/reference/api/api-keys\#query-parameters/index.html) FieldDescription `type``"bearer" | "public_key"` Only this credential family. Every key is bearer, so public\_key returns an empty list. `limit``integer` Maximum number of items to return. Default 50, maximum 500; larger values are capped. `page_token``string` next\_page\_token from the previous page. `ascending``boolean` Oldest first. #### [Response](/content/docs/reference/api/api-keys\#response/index.html) **200** A page of keys (`application/json`) FieldDescription `count``integer`Required Number of items returned. `limit``integer`Required Page size used. `next_page_token``string` Page token for pagination. Absent on the last page. `api_keys` [BearerApiKey\[\]](/content/docs/reference/api/objects#bearerapikey/index.html) Required Keys in the route scope that are not revoked, ordered by created\_at, newest first unless ascending is set. Each item of `api_keys` is a [BearerApiKey](/content/docs/reference/api/objects#bearerapikey/index.html): FieldDescription `type``"bearer"`Required Always bearer: MachineMail has no public-key credentials. `api_key_id``string`Required ID of the API key. `prefix``string`Required First 12 characters of the key (mm\_live\_ and 4 more), safe to display. `name``string`Required 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](/content/docs/reference/api/objects#apikeypermissions/index.html) 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``string`Required 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. #### [Errors](/content/docs/reference/api/api-keys\#errors/index.html) | Status | Meaning | | --- | --- | | `400` | Invalid request: error.type is validation and error.param names the field. | | `401` | Missing, invalid, expired or revoked credential. | | `403` | The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account\_suspended: error.message says what still works; do not retry or re-register). | | `500` | Unexpected server error. | Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/api-keys\#example/index.html) Request ``` curl "https://api.machinemail.dev/v0/api-keys" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" ``` Response 200 ``` { "count": 1, "limit": 50, "next_page_token": "eyJvIjo1MH0", "api_keys": [\ {\ "type": "bearer",\ "api_key_id": "key_01k6x3e8mr0000h4r0ty6c9k1n",\ "prefix": "mm_live_4f8K",\ "name": "Production",\ "pod_id": "pod_01k6x2m9qd0001b8j4mr0w3d5f",\ "inbox_id": "agent@machinemail.dev",\ "permissions": {\ "*": false,\ "inbox_read": false,\ "inbox_create": false,\ "inbox_update": false,\ "inbox_delete": false,\ "thread_read": false,\ "thread_delete": false,\ "message_read": false,\ "message_reply": false,\ "message_send": false,\ "message_update": false,\ "message_delete": false,\ "label_spam_read": false,\ "label_blocked_read": false,\ "label_unauthenticated_read": false,\ "label_trash_read": false,\ "draft_read": false,\ "draft_create": false,\ "draft_update": false,\ "draft_delete": false,\ "draft_send": false,\ "webhook_read": false,\ "webhook_create": false,\ "webhook_update": false,\ "webhook_delete": false,\ "domain_read": false,\ "domain_create": false,\ "domain_update": false,\ "domain_delete": false,\ "list_entry_read": false,\ "list_entry_create": false,\ "list_entry_delete": false,\ "trusted_domain_read": false,\ "trusted_domain_create": false,\ "trusted_domain_update": false,\ "trusted_domain_delete": false,\ "metrics_read": false,\ "api_key_read": false,\ "api_key_create": false,\ "api_key_update": false,\ "api_key_delete": false,\ "pod_read": false,\ "pod_create": false,\ "pod_update": false,\ "pod_delete": false,\ "inbound_raw": false\ },\ "created_at": "2026-10-01T12:00:00.000Z",\ "expires_at": "2026-10-01T12:00:00.000Z",\ "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",\ "used_at": "2026-10-01T12:00:00.000Z",\ "revoked_at": "2026-10-01T12:00:00.000Z",\ "updated_at": "2026-10-01T12:00:00.000Z"\ }\ ] } ``` ## [Create API Key](/content/docs/reference/api/api-keys\#create-api-key/index.html) http ``` POST /v0/api-keys ``` The route sets the scope of the new key: `POST /v0/api-keys` makes an organization key, `POST /v0/pods/{pod_id}/api-keys` a pod key, `POST /v0/inboxes/{inbox_id}/api-keys` an inbox key. Only organization-scoped credentials (and dashboard sessions) can create keys, and only with permissions they have themselves (`403`). `api_key` is returned once. `expires_at` makes a key that stops working at that time (`401` after it). A key created with an expiring API key never outlives it. **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `api_key_create`. #### [Request body](/content/docs/reference/api/api-keys\#request-body/index.html) Content type: `application/json`. 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. #### [Response](/content/docs/reference/api/api-keys\#response-1/index.html) **201** Created. api\_key is shown once. (`application/json`) FieldDescription `api_key_id``string`Required ID of the API key. `prefix``string`Required First 12 characters of the key (mm\_live\_ and 4 more), safe to display. `name``string`Required 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](/content/docs/reference/api/objects#apikeypermissions/index.html) `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``string`Required The key itself (mm\_live\_ and 32 characters). Returned once; only a hash is stored. `permissions` is a [ApiKeyPermissions](/content/docs/reference/api/objects#apikeypermissions/index.html): 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. #### [Errors](/content/docs/reference/api/api-keys\#errors-1/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/api-keys\#example-1/index.html) Request ``` curl -X POST "https://api.machinemail.dev/v0/api-keys" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Production" }' ``` Response 201 ``` { "api_key_id": "key_01k6x3e8mr0000h4r0ty6c9k1n", "prefix": "mm_live_4f8K", "name": "Production", "pod_id": "pod_01k6x2m9qd0001b8j4mr0w3d5f", "inbox_id": "agent@machinemail.dev", "permissions": { "*": false, "inbox_read": false, "inbox_create": false, "inbox_update": false, "inbox_delete": false, "thread_read": false, "thread_delete": false, "message_read": false, "message_reply": false, "message_send": false, "message_update": false, "message_delete": false, "label_spam_read": false, "label_blocked_read": false, "label_unauthenticated_read": false, "label_trash_read": false, "draft_read": false, "draft_create": false, "draft_update": false, "draft_delete": false, "draft_send": false, "webhook_read": false, "webhook_create": false, "webhook_update": false, "webhook_delete": false, "domain_read": false, "domain_create": false, "domain_update": false, "domain_delete": false, "list_entry_read": false, "list_entry_create": false, "list_entry_delete": false, "trusted_domain_read": false, "trusted_domain_create": false, "trusted_domain_update": false, "trusted_domain_delete": false, "metrics_read": false, "api_key_read": false, "api_key_create": false, "api_key_update": false, "api_key_delete": false, "pod_read": false, "pod_create": false, "pod_update": false, "pod_delete": false, "inbound_raw": false }, "created_at": "2026-10-01T12:00:00.000Z", "expires_at": "2026-10-01T12:00:00.000Z", "api_key": "mm_live_4f8Kq2ZbX9mN3pR7tV1wY6cH0jL5sD8a" } ``` ## [Get API Key](/content/docs/reference/api/api-keys\#get-api-key/index.html) http ``` GET /v0/api-keys/{api_key_id} ``` Also returns revoked keys (with `revoked_at`). **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `api_key_read`. #### [Path parameters](/content/docs/reference/api/api-keys\#path-parameters/index.html) FieldDescription `api_key_id``string`Required ID of the API key. #### [Response](/content/docs/reference/api/api-keys\#response-2/index.html) **200** The key (`application/json`) FieldDescription `type``"bearer"`Required Always bearer: MachineMail has no public-key credentials. `api_key_id``string`Required ID of the API key. `prefix``string`Required First 12 characters of the key (mm\_live\_ and 4 more), safe to display. `name``string`Required 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](/content/docs/reference/api/objects#apikeypermissions/index.html) `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``string`Required 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. `permissions` is a [ApiKeyPermissions](/content/docs/reference/api/objects#apikeypermissions/index.html): 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. #### [Errors](/content/docs/reference/api/api-keys\#errors-2/index.html) | Status | Meaning | | --- | --- | | `401` | Missing, invalid, expired or revoked credential. | | `403` | The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account\_suspended: error.message says what still works; do not retry or re-register). | | `404` | Not found. Also returned for resources outside the credential scope. | | `500` | Unexpected server error. | Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/api-keys\#example-2/index.html) Request ``` curl "https://api.machinemail.dev/v0/api-keys/key_01k6x3e8mr0000h4r0ty6c9k1n" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" ``` Response 200 ``` { "type": "bearer", "api_key_id": "key_01k6x3e8mr0000h4r0ty6c9k1n", "prefix": "mm_live_4f8K", "name": "Production", "pod_id": "pod_01k6x2m9qd0001b8j4mr0w3d5f", "inbox_id": "agent@machinemail.dev", "permissions": { "*": false, "inbox_read": false, "inbox_create": false, "inbox_update": false, "inbox_delete": false, "thread_read": false, "thread_delete": false, "message_read": false, "message_reply": false, "message_send": false, "message_update": false, "message_delete": false, "label_spam_read": false, "label_blocked_read": false, "label_unauthenticated_read": false, "label_trash_read": false, "draft_read": false, "draft_create": false, "draft_update": false, "draft_delete": false, "draft_send": false, "webhook_read": false, "webhook_create": false, "webhook_update": false, "webhook_delete": false, "domain_read": false, "domain_create": false, "domain_update": false, "domain_delete": false, "list_entry_read": false, "list_entry_create": false, "list_entry_delete": false, "trusted_domain_read": false, "trusted_domain_create": false, "trusted_domain_update": false, "trusted_domain_delete": false, "metrics_read": false, "api_key_read": false, "api_key_create": false, "api_key_update": false, "api_key_delete": false, "pod_read": false, "pod_create": false, "pod_update": false, "pod_delete": false, "inbound_raw": false }, "created_at": "2026-10-01T12:00:00.000Z", "expires_at": "2026-10-01T12:00:00.000Z", "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e", "used_at": "2026-10-01T12:00:00.000Z", "revoked_at": "2026-10-01T12:00:00.000Z", "updated_at": "2026-10-01T12:00:00.000Z" } ``` ## [Update API Key](/content/docs/reference/api/api-keys\#update-api-key/index.html) http ``` PATCH /v0/api-keys/{api_key_id} ``` Rename a key or replace its permissions. Only organization-scoped credentials (and dashboard sessions) can update keys, and cannot grant permissions they lack (`403`). **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `api_key_update`. #### [Path parameters](/content/docs/reference/api/api-keys\#path-parameters-1/index.html) FieldDescription `api_key_id``string`Required ID of the API key. #### [Request body](/content/docs/reference/api/api-keys\#request-body-1/index.html) Content type: `application/json`. Fields you omit are unchanged. `permissions` replaces the permission object in full. Scope and expiry cannot be changed. FieldDescription `name``string` New name. A blank name is ignored. `permissions``object` New permissions; replaces the permission object in full. #### [Response](/content/docs/reference/api/api-keys\#response-3/index.html) **200** The updated key (`application/json`) FieldDescription `type``"bearer"`Required Always bearer: MachineMail has no public-key credentials. `api_key_id``string`Required ID of the API key. `prefix``string`Required First 12 characters of the key (mm\_live\_ and 4 more), safe to display. `name``string`Required 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](/content/docs/reference/api/objects#apikeypermissions/index.html) `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``string`Required 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. `permissions` is a [ApiKeyPermissions](/content/docs/reference/api/objects#apikeypermissions/index.html): 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. #### [Errors](/content/docs/reference/api/api-keys\#errors-3/index.html) | Status | Meaning | | --- | --- | | `400` | Invalid request: error.type is validation and error.param names the field. | | `401` | Missing, invalid, expired or revoked credential. | | `403` | The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account\_suspended: error.message says what still works; do not retry or re-register). | | `404` | Not found. Also returned for resources outside the credential scope. | | `500` | Unexpected server error. | Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/api-keys\#example-3/index.html) Request ``` curl -X PATCH "https://api.machinemail.dev/v0/api-keys/key_01k6x3e8mr0000h4r0ty6c9k1n" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Production" }' ``` Response 200 ## [Delete API Key](/content/docs/reference/api/api-keys\#delete-api-key/index.html) http ``` DELETE /v0/api-keys/{api_key_id} ``` Revokes the key: it stops working immediately. The record is kept (with `revoked_at`) and no longer listed. **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `api_key_delete`. #### [Path parameters](/content/docs/reference/api/api-keys\#path-parameters-2/index.html) FieldDescription `api_key_id``string`Required ID of the API key. #### [Response](/content/docs/reference/api/api-keys\#response-4/index.html) **200** Revoked (`application/json`) FieldDescription `ok``true`Required #### [Errors](/content/docs/reference/api/api-keys\#errors-4/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/api-keys\#example-4/index.html) Request ``` curl -X DELETE "https://api.machinemail.dev/v0/api-keys/key_01k6x3e8mr0000h4r0ty6c9k1n" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" ``` Response 200 ``` { "ok": true } ``` ## [List API Keys in Inbox](/content/docs/reference/api/api-keys\#list-api-keys-in-inbox/index.html) http ``` GET /v0/inboxes/{inbox_id}/api-keys ``` Same as List API Keys (`GET /v0/api-keys`), limited to the inbox. **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `api_key_read`. #### [Path parameters](/content/docs/reference/api/api-keys\#path-parameters-3/index.html) FieldDescription `inbox_id``string`Required ID of the inbox. #### [Query parameters](/content/docs/reference/api/api-keys\#query-parameters-1/index.html) FieldDescription `type``"bearer" | "public_key"` Only this credential family. Every key is bearer, so public\_key returns an empty list. `limit``integer` Maximum number of items to return. Default 50, maximum 500; larger values are capped. `page_token``string` next\_page\_token from the previous page. `ascending``boolean` Oldest first. #### [Response](/content/docs/reference/api/api-keys\#response-5/index.html) **200** A page of keys (`application/json`) FieldDescription `count``integer`Required Number of items returned. `limit``integer`Required Page size used. `next_page_token``string` Page token for pagination. Absent on the last page. `api_keys` [BearerApiKey\[\]](/content/docs/reference/api/objects#bearerapikey/index.html) Required Keys in the route scope that are not revoked, ordered by created\_at, newest first unless ascending is set. Each item of `api_keys` is a [BearerApiKey](/content/docs/reference/api/objects#bearerapikey/index.html): FieldDescription `type``"bearer"`Required Always bearer: MachineMail has no public-key credentials. `api_key_id``string`Required ID of the API key. `prefix``string`Required First 12 characters of the key (mm\_live\_ and 4 more), safe to display. `name``string`Required 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](/content/docs/reference/api/objects#apikeypermissions/index.html) `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``string`Required 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. #### [Errors](/content/docs/reference/api/api-keys\#errors-5/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/api-keys\#example-5/index.html) Request ``` curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/api-keys" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" ``` Response 200 ## [Create API Key in Inbox](/content/docs/reference/api/api-keys\#create-api-key-in-inbox/index.html) http ``` POST /v0/inboxes/{inbox_id}/api-keys ``` Same as Create API Key (`POST /v0/api-keys`), limited to the inbox. **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `api_key_create`. #### [Path parameters](/content/docs/reference/api/api-keys\#path-parameters-4/index.html) FieldDescription `inbox_id``string`Required ID of the inbox. #### [Request body](/content/docs/reference/api/api-keys\#request-body-2/index.html) Content type: `application/json`. 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` #### [Response](/content/docs/reference/api/api-keys\#response-6/index.html) **201** Created. api\_key is shown once. (`application/json`) FieldDescription `api_key_id``string`Required ID of the API key. `prefix``string`Required First 12 characters of the key (mm\_live\_ and 4 more), safe to display. `name``string`Required 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](/content/docs/reference/api/objects#apikeypermissions/index.html) `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``string`Required The key itself (mm\_live\_ and 32 characters). Returned once; only a hash is stored. `permissions` is a [ApiKeyPermissions](/content/docs/reference/api/objects#apikeypermissions/index.html): 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. #### [Errors](/content/docs/reference/api/api-keys\#errors-6/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/api-keys\#example-6/index.html) Request ``` curl -X POST "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/api-keys" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Production" }' ``` Response 201 ## [Get API Key in Inbox](/content/docs/reference/api/api-keys\#get-api-key-in-inbox/index.html) http ``` GET /v0/inboxes/{inbox_id}/api-keys/{api_key_id} ``` Same as Get API Key (`GET /v0/api-keys/{api_key_id}`), limited to the inbox. **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `api_key_read`. #### [Path parameters](/content/docs/reference/api/api-keys\#path-parameters-5/index.html) FieldDescription `inbox_id``string`Required ID of the inbox. `api_key_id``string`Required ID of the API key. #### [Response](/content/docs/reference/api/api-keys\#response-7/index.html) **200** The key (`application/json`) FieldDescription `type``"bearer"`Required Always bearer: MachineMail has no public-key credentials. `api_key_id``string`Required ID of the API key. `prefix``string`Required First 12 characters of the key (mm\_live\_ and 4 more), safe to display. `name``string`Required 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](/content/docs/reference/api/objects#apikeypermissions/index.html) `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``string`Required 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. `permissions` is a [ApiKeyPermissions](/content/docs/reference/api/objects#apikeypermissions/index.html): 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. #### [Errors](/content/docs/reference/api/api-keys\#errors-7/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/api-keys\#example-7/index.html) Request ``` curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/api-keys/key_01k6x3e8mr0000h4r0ty6c9k1n" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" ``` Response 200 ## [Update API Key in Inbox](/content/docs/reference/api/api-keys\#update-api-key-in-inbox/index.html) http ``` PATCH /v0/inboxes/{inbox_id}/api-keys/{api_key_id} ``` Same as Update API Key (`PATCH /v0/api-keys/{api_key_id}`), limited to the inbox. **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `api_key_update`. #### [Path parameters](/content/docs/reference/api/api-keys\#path-parameters-6/index.html) FieldDescription `inbox_id``string`Required ID of the inbox. `api_key_id``string`Required ID of the API key. #### [Request body](/content/docs/reference/api/api-keys\#request-body-3/index.html) Content type: `application/json`. Fields you omit are unchanged. `permissions` replaces the permission object in full. Scope and expiry cannot be changed. FieldDescription `name``string` New name. A blank name is ignored. `permissions``object` New permissions; replaces the permission object in full. #### [Response](/content/docs/reference/api/api-keys\#response-8/index.html) **200** The updated key (`application/json`) FieldDescription `type``"bearer"`Required Always bearer: MachineMail has no public-key credentials. `api_key_id``string`Required ID of the API key. `prefix``string`Required First 12 characters of the key (mm\_live\_ and 4 more), safe to display. `name``string`Required 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](/content/docs/reference/api/objects#apikeypermissions/index.html) `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``string`Required 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. `permissions` is a [ApiKeyPermissions](/content/docs/reference/api/objects#apikeypermissions/index.html): 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. #### [Errors](/content/docs/reference/api/api-keys\#errors-8/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/api-keys\#example-8/index.html) Request ``` curl -X PATCH "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/api-keys/key_01k6x3e8mr0000h4r0ty6c9k1n" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Production" }' ``` Response 200 ## [Delete API Key in Inbox](/content/docs/reference/api/api-keys\#delete-api-key-in-inbox/index.html) http ``` DELETE /v0/inboxes/{inbox_id}/api-keys/{api_key_id} ``` Same as Delete API Key (`DELETE /v0/api-keys/{api_key_id}`), limited to the inbox. **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `api_key_delete`. #### [Path parameters](/content/docs/reference/api/api-keys\#path-parameters-7/index.html) FieldDescription `inbox_id``string`Required ID of the inbox. `api_key_id``string`Required ID of the API key. #### [Response](/content/docs/reference/api/api-keys\#response-9/index.html) **200** Revoked (`application/json`) FieldDescription `ok``true`Required #### [Errors](/content/docs/reference/api/api-keys\#errors-9/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/api-keys\#example-9/index.html) Request ``` curl -X DELETE "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/api-keys/key_01k6x3e8mr0000h4r0ty6c9k1n" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" ``` Response 200 ``` { "ok": true } ``` ## [List API Keys in Pod](/content/docs/reference/api/api-keys\#list-api-keys-in-pod/index.html) http ``` GET /v0/pods/{pod_id}/api-keys ``` Same as List API Keys (`GET /v0/api-keys`), limited to the pod. **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `api_key_read`. #### [Path parameters](/content/docs/reference/api/api-keys\#path-parameters-8/index.html) FieldDescription `pod_id``string`Required ID of the pod. #### [Query parameters](/content/docs/reference/api/api-keys\#query-parameters-2/index.html) FieldDescription `type``"bearer" | "public_key"` Only this credential family. Every key is bearer, so public\_key returns an empty list. `limit``integer` Maximum number of items to return. Default 50, maximum 500; larger values are capped. `page_token``string` next\_page\_token from the previous page. `ascending``boolean` Oldest first. #### [Response](/content/docs/reference/api/api-keys\#response-10/index.html) **200** A page of keys (`application/json`) FieldDescription `count``integer`Required Number of items returned. `limit``integer`Required Page size used. `next_page_token``string` Page token for pagination. Absent on the last page. `api_keys` [BearerApiKey\[\]](/content/docs/reference/api/objects#bearerapikey/index.html) Required Keys in the route scope that are not revoked, ordered by created\_at, newest first unless ascending is set. Each item of `api_keys` is a [BearerApiKey](/content/docs/reference/api/objects#bearerapikey/index.html): FieldDescription `type``"bearer"`Required Always bearer: MachineMail has no public-key credentials. `api_key_id``string`Required ID of the API key. `prefix``string`Required First 12 characters of the key (mm\_live\_ and 4 more), safe to display. `name``string`Required 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](/content/docs/reference/api/objects#apikeypermissions/index.html) `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``string`Required 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. #### [Errors](/content/docs/reference/api/api-keys\#errors-10/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/api-keys\#example-10/index.html) Request ``` curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/api-keys" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" ``` Response 200 ## [Create API Key in Pod](/content/docs/reference/api/api-keys\#create-api-key-in-pod/index.html) http ``` POST /v0/pods/{pod_id}/api-keys ``` Same as Create API Key (`POST /v0/api-keys`), limited to the pod. **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `api_key_create`. #### [Path parameters](/content/docs/reference/api/api-keys\#path-parameters-9/index.html) FieldDescription `pod_id``string`Required ID of the pod. #### [Request body](/content/docs/reference/api/api-keys\#request-body-4/index.html) Content type: `application/json`. 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` #### [Response](/content/docs/reference/api/api-keys\#response-11/index.html) **201** Created. api\_key is shown once. (`application/json`) FieldDescription `api_key_id``string`Required ID of the API key. `prefix``string`Required First 12 characters of the key (mm\_live\_ and 4 more), safe to display. `name``string`Required 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](/content/docs/reference/api/objects#apikeypermissions/index.html) `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``string`Required The key itself (mm\_live\_ and 32 characters). Returned once; only a hash is stored. `permissions` is a [ApiKeyPermissions](/content/docs/reference/api/objects#apikeypermissions/index.html): 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. #### [Errors](/content/docs/reference/api/api-keys\#errors-11/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/api-keys\#example-11/index.html) Request ``` curl -X POST "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/api-keys" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Production" }' ``` Response 201 ## [Get API Key in Pod](/content/docs/reference/api/api-keys\#get-api-key-in-pod/index.html) http ``` GET /v0/pods/{pod_id}/api-keys/{api_key_id} ``` Same as Get API Key (`GET /v0/api-keys/{api_key_id}`), limited to the pod. **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `api_key_read`. #### [Path parameters](/content/docs/reference/api/api-keys\#path-parameters-10/index.html) FieldDescription `pod_id``string`Required ID of the pod. `api_key_id``string`Required ID of the API key. #### [Response](/content/docs/reference/api/api-keys\#response-12/index.html) **200** The key (`application/json`) FieldDescription `type``"bearer"`Required Always bearer: MachineMail has no public-key credentials. `api_key_id``string`Required ID of the API key. `prefix``string`Required First 12 characters of the key (mm\_live\_ and 4 more), safe to display. `name``string`Required 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](/content/docs/reference/api/objects#apikeypermissions/index.html) `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``string`Required 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. `permissions` is a [ApiKeyPermissions](/content/docs/reference/api/objects#apikeypermissions/index.html): 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. #### [Errors](/content/docs/reference/api/api-keys\#errors-12/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/api-keys\#example-12/index.html) Request ``` curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/api-keys/key_01k6x3e8mr0000h4r0ty6c9k1n" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" ``` Response 200 ## [Update API Key in Pod](/content/docs/reference/api/api-keys\#update-api-key-in-pod/index.html) http ``` PATCH /v0/pods/{pod_id}/api-keys/{api_key_id} ``` Same as Update API Key (`PATCH /v0/api-keys/{api_key_id}`), limited to the pod. **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `api_key_update`. #### [Path parameters](/content/docs/reference/api/api-keys\#path-parameters-11/index.html) FieldDescription `pod_id``string`Required ID of the pod. `api_key_id``string`Required ID of the API key. #### [Request body](/content/docs/reference/api/api-keys\#request-body-5/index.html) Content type: `application/json`. Fields you omit are unchanged. `permissions` replaces the permission object in full. Scope and expiry cannot be changed. FieldDescription `name``string` New name. A blank name is ignored. `permissions``object` New permissions; replaces the permission object in full. #### [Response](/content/docs/reference/api/api-keys\#response-13/index.html) **200** The updated key (`application/json`) FieldDescription `type``"bearer"`Required Always bearer: MachineMail has no public-key credentials. `api_key_id``string`Required ID of the API key. `prefix``string`Required First 12 characters of the key (mm\_live\_ and 4 more), safe to display. `name``string`Required 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](/content/docs/reference/api/objects#apikeypermissions/index.html) `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``string`Required 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. `permissions` is a [ApiKeyPermissions](/content/docs/reference/api/objects#apikeypermissions/index.html): 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. #### [Errors](/content/docs/reference/api/api-keys\#errors-13/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/api-keys\#example-13/index.html) Request ``` curl -X PATCH "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/api-keys/key_01k6x3e8mr0000h4r0ty6c9k1n" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Production" }' ``` Response 200 ## [Delete API Key in Pod](/content/docs/reference/api/api-keys\#delete-api-key-in-pod/index.html) http ``` DELETE /v0/pods/{pod_id}/api-keys/{api_key_id} ``` Same as Delete API Key (`DELETE /v0/api-keys/{api_key_id}`), limited to the pod. **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `api_key_delete`. #### [Path parameters](/content/docs/reference/api/api-keys\#path-parameters-12/index.html) FieldDescription `pod_id``string`Required ID of the pod. `api_key_id``string`Required ID of the API key. #### [Response](/content/docs/reference/api/api-keys\#response-14/index.html) **200** Revoked (`application/json`) FieldDescription `ok``true`Required #### [Errors](/content/docs/reference/api/api-keys\#errors-14/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/api-keys\#example-14/index.html) Request ``` curl -X DELETE "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/api-keys/key_01k6x3e8mr0000h4r0ty6c9k1n" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" ``` Response 200 ``` { "ok": true } ``` On this page [List API Keys](/content/docs/reference/api/api-keys#list-api-keys/index.html) [Create API Key](/content/docs/reference/api/api-keys#create-api-key/index.html) [Get API Key](/content/docs/reference/api/api-keys#get-api-key/index.html) [Update API Key](/content/docs/reference/api/api-keys#update-api-key/index.html) [Delete API Key](/content/docs/reference/api/api-keys#delete-api-key/index.html) [List API Keys in Inbox](/content/docs/reference/api/api-keys#list-api-keys-in-inbox/index.html) [Create API Key in Inbox](/content/docs/reference/api/api-keys#create-api-key-in-inbox/index.html) [Get API Key in Inbox](/content/docs/reference/api/api-keys#get-api-key-in-inbox/index.html) [Update API Key in Inbox](/content/docs/reference/api/api-keys#update-api-key-in-inbox/index.html) [Delete API Key in Inbox](/content/docs/reference/api/api-keys#delete-api-key-in-inbox/index.html) [List API Keys in Pod](/content/docs/reference/api/api-keys#list-api-keys-in-pod/index.html) [Create API Key in Pod](/content/docs/reference/api/api-keys#create-api-key-in-pod/index.html) [Get API Key in Pod](/content/docs/reference/api/api-keys#get-api-key-in-pod/index.html) [Update API Key in Pod](/content/docs/reference/api/api-keys#update-api-key-in-pod/index.html) [Delete API Key in Pod](/content/docs/reference/api/api-keys#delete-api-key-in-pod/index.html) 100% readTop