Skip to content
machinemail

Pods

Pods group inboxes, domains and webhooks.

MethodPathSummary
GET/v0/podsList Pods
POST/v0/podsCreate 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

limitinteger
Maximum number of items to return. Default 50, maximum 500; larger values are capped.
page_tokenstring
next_page_token from the previous page.
ascendingboolean
Sort oldest first.

Response

200 A page of pods (application/json)

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

Each item of pods is a Pod:

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

Errors

StatusMeaning
400Invalid request: error.type is validation and error.param names the field.
401Missing, invalid, expired or revoked credential.
403The 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).
500Unexpected server error.

Error bodies use the error envelope.

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.

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

Response

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

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

201 Created (application/json)

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

Errors

StatusMeaning
400Invalid request: error.type is validation and error.param names the field.
401Missing, invalid, expired or revoked credential.
403The 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).
500Unexpected server error.

Error bodies use the error envelope.

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

pod_idstringRequired
ID of the pod.

Response

200 The pod (application/json)

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

Errors

StatusMeaning
401Missing, invalid, expired or revoked credential.
403The 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).
404Not found. Also returned for resources outside the credential scope.
500Unexpected server error.

Error bodies use the error envelope.

Example

Request
curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
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"
}

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

pod_idstringRequired
ID of the pod.

Request body

Content type: application/json.

namestring
New name. Must not be blank.

Response

200 The updated pod (application/json)

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

Errors

StatusMeaning
400Invalid request: error.type is validation and error.param names the field.
401Missing, invalid, expired or revoked credential.
403The 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).
404Not found. Also returned for resources outside the credential scope.
500Unexpected server error.

Error bodies use the error envelope.

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

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

pod_idstringRequired
ID of the pod.

Response

200 Deleted (application/json)

oktrueRequired

Errors

StatusMeaning
401Missing, invalid, expired or revoked credential.
403The 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).
404Not found. Also returned for resources outside the credential scope.
409Conflicts with an existing resource.
500Unexpected server error.

Error bodies use the error envelope.

Example

Request
curl -X DELETE "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
Response 200
{
  "ok": true
}

On this page

List PodsCreate PodGet PodUpdate PodDelete Pod
0% read