pods.md

title: "Pods" description: "Create, list, update and delete pods: groups of inboxes, domains and webhooks that keep each tenant separate inside one MachineMail organization." canonical: "https://machinemail.dev/docs/reference/api/pods"

Pods

Create, list, update and delete pods: groups of inboxes, domains and webhooks that keep each tenant separate inside one MachineMail organization.

Source: https://machinemail.dev/docs/reference/api/pods

Method Path Summary
GET /v0/pods List Pods
POST /v0/pods Create Pod
GET /v0/pods/{pod_id} Get Pod
PATCH /v0/pods/{pod_id} Update Pod
DELETE /v0/pods/{pod_id} Delete Pod

List Pods

GET /v0/pods

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

Query parameters

Field Type Description
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 Sort oldest first.

Response

200 A page of pods (application/json)

Field Type Description
count integer required Number of items returned.
limit integer Maximum number of items per page. Default 50, maximum 500; larger values are capped.
next_page_token string Page token for pagination. Absent on the last page.
pods Pod[] required Ordered by created_at, newest first unless ascending is set. A pod credential sees only its pod.

Each item of pods is a Pod:

Field Type Description
pod_id string required ID of the pod.
organization_id string required ID of the organization.
name string required Name of the pod.
is_default boolean required Whether this is the default pod, where inboxes go when no pod is given. It cannot be deleted.
client_id string Client ID given at creation (idempotency key).
updated_at string (date-time) required Time at which the pod was last updated.
created_at string (date-time) required Time at which the pod was created.

Errors

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.

Example

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

{
  "count": 1,
  "limit": 50,
  "next_page_token": "eyJvIjo1MH0",
  "pods": [
    {
      "pod_id": "pod_01k6x2m9qd0001b8j4mr0w3d5f",
      "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
      "name": "Production",
      "is_default": true,
      "client_id": "my-client-id",
      "updated_at": "2026-10-01T12:00:00.000Z",
      "created_at": "2026-10-01T12:00:00.000Z"
    }
  ]
}

Create Pod

POST /v0/pods

Organization-scoped credentials only: pod and inbox credentials get 403.

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

Request body

Content type: application/json.

Field Type Description
name string Name of the pod. Default Untitled pod.
client_id string Idempotency key: a create with a client_id already used in the organization returns that pod with 200.

Response

200 A pod with this client_id already exists; it is returned unchanged. (application/json)

Field Type Description
pod_id string required ID of the pod.
organization_id string required ID of the organization.
name string required Name of the pod.
is_default boolean required Whether this is the default pod, where inboxes go when no pod is given. It cannot be deleted.
client_id string Client ID given at creation (idempotency key).
updated_at string (date-time) required Time at which the pod was last updated.
created_at string (date-time) required Time at which the pod was created.

201 Created (application/json)

Errors

Error bodies use the error envelope.

Example

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

{
  "pod_id": "pod_01k6x2m9qd0001b8j4mr0w3d5f",
  "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
  "name": "Production",
  "is_default": true,
  "client_id": "my-client-id",
  "updated_at": "2026-10-01T12:00:00.000Z",
  "created_at": "2026-10-01T12:00:00.000Z"
}

Get Pod

GET /v0/pods/{pod_id}

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

Path parameters

Field Type Description
pod_id string required ID of the pod.

Response

200 The pod (application/json)

Field Type Description
pod_id string required ID of the pod.
organization_id string required ID of the organization.
name string required Name of the pod.
is_default boolean required Whether this is the default pod, where inboxes go when no pod is given. It cannot be deleted.
client_id string Client ID given at creation (idempotency key).
updated_at string (date-time) required Time at which the pod was last updated.
created_at string (date-time) required Time at which the pod was created.

Errors

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.

Example

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

Update Pod

PATCH /v0/pods/{pod_id}

Rename the pod.

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

Path parameters

Field Type Description
pod_id string required ID of the pod.

Request body

Content type: application/json.

Field Type Description
name string New name. Must not be blank.

Response

200 The updated pod (application/json)

Errors

Error bodies use the error envelope.

Example

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

Delete Pod

DELETE /v0/pods/{pod_id}

The default pod, and pods that still have inboxes, cannot be deleted (409).

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

Path parameters

Field Type Description
pod_id string required ID of the pod.

Response

200 Deleted (application/json)

Field Type Description
ok true required

Errors

Error bodies use the error envelope.

Example

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

{
  "ok": true
}