---
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](https://machinemail.dev/docs/cli/commands#global-flags).

## 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`](https://machinemail.dev/docs/reference/api/pods#create-pod)

## 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}`](https://machinemail.dev/docs/reference/api/pods#delete-pod)

## pods get

Get pod.

Requires the pod\_read permission.

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

#### Arguments

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

#### Examples

```bash
machinemail pods get pod_01m4fykg210000x6z8b6wc2rdx
```

#### API

- [`GET /v0/pods/{pod_id}`](https://machinemail.dev/docs/reference/api/pods#get-pod)

## 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`](https://machinemail.dev/docs/reference/api/pods#list-pods)

## 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}`](https://machinemail.dev/docs/reference/api/pods#update-pod)