---
title: "pods"
description: "Pods group inboxes, domains and webhooks. The `machinemail pods` commands: arguments, flags, examples and the API routes they call."
canonical: "https://machinemail.dev/docs/cli/commands/pods"
---

# pods

> Pods group inboxes, domains and webhooks. The `machinemail pods` commands: arguments, flags, examples and the API routes they call.

Source: https://machinemail.dev/docs/cli/commands/pods

Pods group inboxes, domains and webhooks. Also spelled `pod`.

| Command                       | Summary    |
| ----------------------------- | ---------- |
| [`pods create`](#pods-create) | Create pod |
| [`pods delete`](#pods-delete) | Delete pod |
| [`pods get`](#pods-get)       | Get pod    |
| [`pods list`](#pods-list)     | List pods  |
| [`pods update`](#pods-update) | Update pod |

Every command also takes the [global flags](/content/docs/cli/commands#global-flags/index.html).

## pods create

Create pod.

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

Requires the pod_create permission.

```bash
machinemail pods create [flags]
```

#### Flags

| Field                | Type      |   | Description                                                                                     |
| -------------------- | --------- | - | ----------------------------------------------------------------------------------------------- |
| `--name <value>`     | `string`  |   | Name of the pod. Default Untitled pod. Default: `Untitled pod`.                              |
| `--client-id <id>`   | `string`  |   | Idempotency key: a create with a --client-id already used in the organization returns that pod with 200. |
| `-d, --data <json|@file|->` | `string`  |   | Request body as JSON, @file or - for stdin; field flags override its keys.                 |

#### Examples

```bash
machinemail pods create
machinemail pods create --data @body.json
```

#### API

- [`POST /v0/pods`](/content/docs/reference/api/pods#create-pod/index.html)

## pods delete

Delete pod.

Also: `machinemail pods rm`.

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

Requires the pod_delete permission.

```bash
machinemail pods delete <pod-id> [flags]
```

#### Arguments

| Field      | Type      |   | Description                              |
| ---------- | --------- | - | ---------------------------------------- |
| `<pod-id>` | `string`  | required | ID of the pod.                           |

#### Examples

```bash
machinemail pods delete pod_01m4fykg210000x6z8b6wc2rdx
```

#### API

- [`DELETE /v0/pods/{pod_id}`](/content/docs/reference/api/pods#delete-pod/index.html)

## pods get

Get pod.

Requires the pod_read permission.

```bash
machinemail pods get <pod-id> [flags]
```

#### Arguments

#### Examples

```bash
machinemail pods get pod_01m4fykg210000x6z8b6wc2rdx
```

#### API

- [`GET /v0/pods/{pod_id}`](/content/docs/reference/api/pods#get-pod/index.html)

## pods list

List pods.

Also: `machinemail pods ls`.

Requires the pod_read permission.

```bash
machinemail pods list [flags]
```

#### Flags

| Field                 | Type      |   | Description                                                               |
| --------------------- | --------- | - | ------------------------------------------------------------------------- |
| `--limit <n>`        | `integer` |   | Maximum number of items to return. Default 50, maximum 500; larger values are capped. Default: `50`. |
| `--page-token <value>`| `string`  |   | next_page_token from the previous page.                                 |
| `--ascending`        | `boolean` |   | Sort oldest first.                                                      |
| `--all`             | `boolean` |   | Follow next_page_token and return every page.                          |

#### Examples

```bash
machinemail pods list
machinemail pods list --all --json | jq '.pods | length'
```

#### API

- [`GET /v0/pods`](/content/docs/reference/api/pods#list-pods/index.html)

## pods update

Update pod.

Rename the pod.

Requires the pod_update permission.

```bash
machinemail pods update <pod-id> [flags]
```

#### Arguments

| Field      | Type      |   | Description                       |
| ---------- | --------- | - | --------------------------------- |
| `<pod-id>` | `string`  | required | ID of the pod.                  |

#### Flags

| Field                  | Type      |   | Description                                     |
| ---------------------- | --------- | - | ------------------------------------------------ |
| `--name <value>`      | `string`  |   | New name. Must not be blank.                  |
| `-d, --data <json|@file|->` | `string` |   | Request body as JSON, @file or - for stdin; field flags override its keys. |

#### Examples

```bash
machinemail pods update pod_01m4fykg210000x6z8b6wc2rdx
machinemail pods update pod_01m4fykg210000x6z8b6wc2rdx --data @body.json
```

#### API

- [`PATCH /v0/pods/{pod_id}`](/content/docs/reference/api/pods#update-pod/index.html)