# List Pods

| Method | Path | Summary |
| --- | --- | --- |
| `GET` | `/v0/pods` | [List Pods](/content/docs/reference/api/pods#list-pods/index.html) |
| `POST` | `/v0/pods` | [Create Pod](/content/docs/reference/api/pods#create-pod/index.html) |
| `GET` | `/v0/pods/{pod_id}` | [Get Pod](/content/docs/reference/api/pods#get-pod/index.html) |
| `PATCH` | `/v0/pods/{pod_id}` | [Update Pod](/content/docs/reference/api/pods#update-pod/index.html) |
| `DELETE` | `/v0/pods/{pod_id}` | [Delete Pod](/content/docs/reference/api/pods#delete-pod/index.html) |

## [List Pods](/content/docs/reference/api/pods#list-pods/index.html)

http

```
GET /v0/pods
```

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

#### [Query parameters](/content/docs/reference/api/pods#query-parameters/index.html)

| 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](/content/docs/reference/api/pods#response/index.html)

**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](/content/docs/reference/api/objects#pod/index.html):

| 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](/content/docs/reference/api/pods#errors/index.html)

| 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](/content/docs/reference/api/pods#example/index.html)

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](/content/docs/reference/api/pods#create-pod/index.html)

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/docs/reference/api/pods#request-body/index.html)

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](/content/docs/reference/api/pods#response-1/index.html)

**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](/content/docs/reference/api/pods#errors-1/index.html)

#### [Example](/content/docs/reference/api/pods#example-1/index.html)

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](/content/docs/reference/api/pods#get-pod/index.html)

http

```
GET /v0/pods/{pod_id}
```

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

#### [Path parameters](/content/docs/reference/api/pods#path-parameters/index.html)

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

#### [Response](/content/docs/reference/api/pods#response-2/index.html)

**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](/content/docs/reference/api/pods#errors-2/index.html)

| 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](/content/docs/reference/api/pods#example-2/index.html)

Request

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

Response 200

## [Update Pod](/content/docs/reference/api/pods#update-pod/index.html)

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](/content/docs/reference/api/pods#path-parameters-1/index.html)

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

#### [Request body](/content/docs/reference/api/pods#request-body-1/index.html)

Content type: `application/json`.

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

#### [Response](/content/docs/reference/api/pods#response-3/index.html)

**200** The updated pod (`application/json`)

#### [Errors](/content/docs/reference/api/pods#errors-3/index.html)

| 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](/content/docs/reference/api/pods#example-3/index.html)

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](/content/docs/reference/api/pods#delete-pod/index.html)

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](/content/docs/reference/api/pods#path-parameters-2/index.html)

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

#### [Response](/content/docs/reference/api/pods#response-4/index.html)

**200** Deleted (`application/json`)

| Field | Description           |
| ----- | ---------------------|
| `ok` | Required: true       |

#### [Errors](/content/docs/reference/api/pods#errors-4/index.html)

| 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](/content/docs/reference/api/pods#example-4/index.html)

Request

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

Response 200

```
{
  "ok": true
}
```