title: "API Keys" description: "Create, list, update and delete MachineMail API keys scoped to the whole organization, to one pod or to a single inbox, each with its own permissions." canonical: "https://machinemail.dev/docs/reference/api/api-keys"

API Keys

Create, list, update and delete MachineMail API keys scoped to the whole organization, to one pod or to a single inbox, each with its own permissions.

Source: https://machinemail.dev/docs/reference/api/api-keys

List API Keys

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 <api key> or the dashboard mm_session cookie. Permission: api_key_read.

Query parameters

Response

200 A page of keys (application/json)

Each item of api_keys is a BearerApiKey:

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/v0/api-keys" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

{
  "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

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 <api key> or the dashboard mm_session cookie. Permission: api_key_create.

Request body

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.

Response

201 Created. api_key is shown once. (application/json)

permissions is a ApiKeyPermissions:

Errors

Error bodies use the error envelope.

Example

curl -X POST "https://api.machinemail.dev/v0/api-keys" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Production"
}'

{
  "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

GET /v0/api-keys/{api_key_id}

Also returns revoked keys (with revoked_at).

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

Path parameters

Response

200 The key (application/json)

permissions is a ApiKeyPermissions:

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/v0/api-keys/key_01k6x3e8mr0000h4r0ty6c9k1n" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

{
  "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

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 <api key> or the dashboard mm_session cookie. Permission: api_key_update.

Path parameters

Request body

Content type: application/json.

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

Response

200 The updated key (application/json)

permissions is a ApiKeyPermissions:

Errors

Error bodies use the error envelope.

Example

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"
}'

Delete API Key

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 <api key> or the dashboard mm_session cookie. Permission: api_key_delete.

Path parameters

Response

200 Revoked (application/json)

Errors

Error bodies use the error envelope.

Example

curl -X DELETE "https://api.machinemail.dev/v0/api-keys/key_01k6x3e8mr0000h4r0ty6c9k1n" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

{
  "ok": true
}

List API Keys in Inbox

GET /v0/inboxes/{inbox_id}/api-keys

Same as List API Keys (GET /v0/api-keys), limited to the inbox.

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

Path parameters

Query parameters

Response

200 A page of keys (application/json)

Each item of api_keys is a BearerApiKey:

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/api-keys" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Create API Key in Inbox

POST /v0/inboxes/{inbox_id}/api-keys

Same as Create API Key (POST /v0/api-keys), limited to the inbox.

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

Path parameters

Request body

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.

Response

201 Created. api_key is shown once. (application/json)

permissions is a ApiKeyPermissions:

Errors

Error bodies use the error envelope.

Example

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"
}'

Get API Key in Inbox

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 <api key> or the dashboard mm_session cookie. Permission: api_key_read.

Path parameters

Response

200 The key (application/json)

permissions is a ApiKeyPermissions:

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/api-keys/key_01k6x3e8mr0000h4r0ty6c9k1n" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Update API Key in Inbox

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 <api key> or the dashboard mm_session cookie. Permission: api_key_update.

Path parameters

Request body

Content type: application/json.

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

Response

200 The updated key (application/json)

permissions is a ApiKeyPermissions:

Errors

Error bodies use the error envelope.

Example

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"
}'

Delete API Key in Inbox

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 <api key> or the dashboard mm_session cookie. Permission: api_key_delete.

Path parameters

Response

200 Revoked (application/json)

Errors

Error bodies use the error envelope.

Example

curl -X DELETE "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/api-keys/key_01k6x3e8mr0000h4r0ty6c9k1n" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

{
  "ok": true
}

List API Keys in Pod

GET /v0/pods/{pod_id}/api-keys

Same as List API Keys (GET /v0/api-keys), limited to the pod.

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

Path parameters

Query parameters

Response

200 A page of keys (application/json)

Each item of api_keys is a BearerApiKey:

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/api-keys" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Create API Key in Pod

POST /v0/pods/{pod_id}/api-keys

Same as Create API Key (POST /v0/api-keys), limited to the pod.

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

Path parameters

Request body

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.

Response

201 Created. api_key is shown once. (application/json)

permissions is a ApiKeyPermissions:

Errors

Error bodies use the error envelope.

Example

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"
}'

Get API Key in Pod

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 <api key> or the dashboard mm_session cookie. Permission: api_key_read.

Path parameters

Response

200 The key (application/json)

permissions is a ApiKeyPermissions:

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/api-keys/key_01k6x3e8mr0000h4r0ty6c9k1n" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Update API Key in Pod

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 <api key> or the dashboard mm_session cookie. Permission: api_key_update.

Path parameters

Request body

Content type: application/json.

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

Response

200 The updated key (application/json)

permissions is a ApiKeyPermissions:

Errors

Error bodies use the error envelope.

Example

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"
}'

Delete API Key in Pod

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 <api key> or the dashboard mm_session cookie. Permission: api_key_delete.

Path parameters

Response

200 Revoked (application/json)

Errors

Error bodies use the error envelope.

Example

curl -X DELETE "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/api-keys/key_01k6x3e8mr0000h4r0ty6c9k1n" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

{
  "ok": true
}