Pods · MachineMail Docs

List 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

http

GET /v0/pods

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

Query parameters

Field	Description
`limit`	Maximum number of items to return. Default 50, maximum 500; larger values are capped.
`page_token`	next_page_token from the previous page.
`ascending`	Sort oldest first.

Response

200 A page of pods (application/json)

Field	Description
`count`	Required: Number of items returned.
`limit`	Maximum number of items per page. Default 50, maximum 500; larger values are capped.
`next_page_token`	Page token for pagination. Absent on the last page.
`pods`	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	Description
`pod_id`	Required: ID of the pod.
`organization_id`	Required: ID of the organization.
`name`	Required: Name of the pod.
`is_default`	Required: Whether this is the default pod, where inboxes go when no pod is given. It cannot be deleted.
`client_id`	Client ID given at creation (idempotency key).
`updated_at`	Required: Time at which the pod was last updated.
`created_at`	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.

Example

Request

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

Response 200

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

http

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	Description
`name`	Name of the pod. Default Untitled pod.
`client_id`	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	Description
`pod_id`	Required: ID of the pod.
`organization_id`	Required: ID of the organization.
`name`	Required: Name of the pod.
`is_default`	Required: Whether this is the default pod, where inboxes go when no pod is given. It cannot be deleted.
`client_id`	Client ID given at creation (idempotency key).
`updated_at`	Required: Time at which the pod was last updated.
`created_at`	Required: Time at which the pod was created.

201 Created (application/json)

Errors

Example

Request

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

Response 200

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

http

GET /v0/pods/{pod_id}

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

Path parameters

Field	Description
`pod_id`	Required: ID of the pod.

Response

200 The pod (application/json)

Field	Description
`pod_id`	Required: ID of the pod.
`organization_id`	Required: ID of the organization.
`name`	Required: Name of the pod.
`is_default`	Required: Whether this is the default pod, where inboxes go when no pod is given. It cannot be deleted.
`client_id`	Client ID given at creation (idempotency key).
`updated_at`	Required: Time at which the pod was last updated.
`created_at`	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.

Example

Request

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

Response 200

Update Pod

http

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	Description
`pod_id`	Required: ID of the pod.

Request body

Content type: application/json.

Field	Description
`name`	New name. Must not be blank.

Response

200 The updated pod (application/json)

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).
`404`	Not found. Also returned for resources outside the credential scope.
`500`	Unexpected server error.

Example

Request

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

Response 200

Delete Pod

http

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	Description
`pod_id`	Required: ID of the pod.

Response

200 Deleted (application/json)

Field	Description
`ok`	Required: true

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.
`409`	Conflicts with an existing resource.
`500`	Unexpected server error.

Example

Request

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

Response 200

{
  "ok": true
}