--- 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](#list-pods) | | `POST` | `/v0/pods` | [Create Pod](#create-pod) | | `GET` | `/v0/pods/{pod_id}` | [Get Pod](#get-pod) | | `PATCH` | `/v0/pods/{pod_id}` | [Update Pod](#update-pod) | | `DELETE` | `/v0/pods/{pod_id}` | [Delete Pod](#delete-pod) | ## List Pods ```http GET /v0/pods ``` **Authentication:** `Authorization: Bearer ` 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](https://machinemail.dev/docs/reference/api/objects#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](https://machinemail.dev/docs/reference/errors). #### Example ```bash title="Request" curl "https://api.machinemail.dev/v0/pods" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" ``` ```json title="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 ` 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`) | 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](https://machinemail.dev/docs/reference/errors). #### Example ```bash title="Request" curl -X POST "https://api.machinemail.dev/v0/pods" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Production" }' ``` ```json title="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 ` 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](https://machinemail.dev/docs/reference/errors). #### Example ```bash title="Request" curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" ``` ```json title="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 ` 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`) | 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). | | `404` | Not found. Also returned for resources outside the credential scope. | | `500` | Unexpected server error. | Error bodies use the [error envelope](https://machinemail.dev/docs/reference/errors). #### Example ```bash title="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" }' ``` ```json title="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 ` 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 | 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. | Error bodies use the [error envelope](https://machinemail.dev/docs/reference/errors). #### Example ```bash title="Request" curl -X DELETE "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" ``` ```json title="Response 200" { "ok": true } ```