> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zapier.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage your inbox

> Pause, resume, update, and delete a trigger inbox.

# Manage your inbox

Once your [trigger inbox](/white-label/trigger-inbox/what-is-trigger-inbox-api) is active, you can pause it to temporarily stop collecting events, resume it when you're ready to continue, update its notification settings, or delete it when you no longer need it. This article covers each operation and explains when to use them.

The Python examples on this page use a `headers` variable defined once at the top of your script:

```python theme={null}
import requests

TOKEN = "your-access-token"
INBOX_ID = "your-inbox-id"

headers = {"Authorization": f"Bearer {TOKEN}"}
```

## Pause an inbox

Pausing stops your inbox from collecting new events. Existing messages already in the queue are preserved and can still be leased while the inbox is paused. Go to [Consuming messages](/white-label/trigger-inbox/consuming-messages) to learn how to lease messages.

Use pause when:

* You need to perform maintenance on your processing service and do not want to build up an overwhelming backlog.
* You want to stop collecting events temporarily without losing the inbox configuration.

<CodeGroup>
  ```bash cURL theme={null}
  curl -s -X POST "https://api.zapier.com/trigger-inbox/api/v1/inboxes/$INBOX_ID/pause" \
    -H "Authorization: Bearer $TOKEN" | python3 -m json.tool
  ```

  ```typescript TypeScript theme={null}
  const res = await fetch(
    `https://api.zapier.com/trigger-inbox/api/v1/inboxes/${INBOX_ID}/pause`,
    { method: "POST", headers: { Authorization: `Bearer ${TOKEN}` } }
  );
  const paused = await res.json();
  console.log(paused.status); // "paused"
  ```

  ```python Python theme={null}
  response = requests.post(
      f"https://api.zapier.com/trigger-inbox/api/v1/inboxes/{INBOX_ID}/pause",
      headers=headers,
  )
  response.raise_for_status()
  print(response.json()["status"])  # "paused"
  ```
</CodeGroup>

A successful response shows `status` changed to `"paused"` and `paused_reason` set to `"user"`.

<Note>
  New events that arrive while the inbox is paused are not queued, they are dropped. If you need to capture all events without interruption, do not pause. Consider leasing with a longer interval instead.
</Note>

## Resume a paused inbox

Resuming restarts event collection. The inbox goes back through [`initializing`](/white-label/trigger-inbox/what-is-trigger-inbox-api#inbox-states) before becoming `active` again.

<CodeGroup>
  ```bash cURL theme={null}
  curl -s -X POST "https://api.zapier.com/trigger-inbox/api/v1/inboxes/$INBOX_ID/resume" \
    -H "Authorization: Bearer $TOKEN" | python3 -m json.tool
  ```

  ```typescript TypeScript theme={null}
  const res = await fetch(
    `https://api.zapier.com/trigger-inbox/api/v1/inboxes/${INBOX_ID}/resume`,
    { method: "POST", headers: { Authorization: `Bearer ${TOKEN}` } }
  );
  const resumed = await res.json();
  console.log(resumed.status); // "initializing"
  ```

  ```python Python theme={null}
  response = requests.post(
      f"https://api.zapier.com/trigger-inbox/api/v1/inboxes/{INBOX_ID}/resume",
      headers=headers,
  )
  response.raise_for_status()
  print(response.json()["status"])  # "initializing"
  ```
</CodeGroup>

The response shows `status` set to `"initializing"`. Poll until the status is `"active"` before resuming message processing. Use the same pattern as [waiting for inbox initialization](/white-label/trigger-inbox/create-trigger-inbox#step-3-wait-for-active).

## Handle an inbox paused by Zapier

Zapier may pause your inbox automatically if a problem is detected. When this happens, the `paused_reason` field tells you why.

Zapier does not send a separate notification when this happens. You detect an automatic pause from the lease response: the `inbox_attributes` include the `paused_reason`, and the lease call returns a [409 once the inbox is paused and fully drained](/white-label/trigger-inbox/consuming-messages#paused-and-drained-409).

Check the `paused_reason` on a paused inbox:

<CodeGroup>
  ```bash cURL theme={null}
  curl -s "https://api.zapier.com/trigger-inbox/api/v1/inboxes/$INBOX_ID" \
    -H "Authorization: Bearer $TOKEN" \
    | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['status'], d.get('paused_reason'))"
  ```

  ```typescript TypeScript theme={null}
  const res = await fetch(
    `https://api.zapier.com/trigger-inbox/api/v1/inboxes/${INBOX_ID}`,
    { headers: { Authorization: `Bearer ${TOKEN}` } }
  );
  const inbox = await res.json();
  console.log(inbox.status, inbox.paused_reason);
  ```

  ```python Python theme={null}
  resp = requests.get(
      f"https://api.zapier.com/trigger-inbox/api/v1/inboxes/{INBOX_ID}",
      headers=headers,
  )
  inbox = resp.json()
  print(inbox["status"], inbox.get("paused_reason"))
  ```
</CodeGroup>

| Paused reason                   | What it means                                                                           | Recommended action                                                    |
| ------------------------------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `user`                          | You paused the inbox manually                                                           | Resume when ready                                                     |
| `authentication`                | The connected app account credentials are invalid or expired                            | Reconnect the app account, then resume                                |
| `authentication_access_revoked` | Access to the connected app was revoked, often because a shared connection was unshared | Reconnect the app account, then resume                                |
| `partner_revoked`               | The app developer or Zapier partner revoked the integration's access                    | Contact Zapier support                                                |
| `subscribe_failed`              | The trigger subscription could not be established                                       | Delete and recreate the inbox; if it persists, contact Zapier support |
| `migrate_failed`                | An internal migration failed                                                            | Contact Zapier support                                                |
| `abandoned`                     | The inbox has not been used for an extended period                                      | Resume if still needed, or delete                                     |
| `upstream_failures`             | The connected app is returning errors                                                   | Wait and retry; if persistent, check the app's status page            |
| `unknown`                       | An unclassified error occurred                                                          | Contact Zapier support                                                |

## Update inbox settings

After creation, only the `notification_url` setting can be updated via PATCH. All other subscription settings (app, trigger, connection, inputs) are fixed at creation time. To change them, delete the inbox and create a new one.

To add or update a notification URL:

<CodeGroup>
  ```bash cURL theme={null}
  curl -s -X PATCH "https://api.zapier.com/trigger-inbox/api/v1/inboxes/$INBOX_ID" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"notification_url": "https://your-server.example.com/inbox-webhook"}' \
    | python3 -m json.tool
  ```

  ```typescript TypeScript theme={null}
  await fetch(`https://api.zapier.com/trigger-inbox/api/v1/inboxes/${INBOX_ID}`, {
    method: "PATCH",
    headers: {
      Authorization: `Bearer ${TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      notification_url: "https://your-server.example.com/inbox-webhook",
    }),
  });
  ```

  ```python Python theme={null}
  requests.patch(
      f"https://api.zapier.com/trigger-inbox/api/v1/inboxes/{INBOX_ID}",
      json={"notification_url": "https://your-server.example.com/inbox-webhook"},
      headers=headers,
  ).raise_for_status()
  ```
</CodeGroup>

To remove the notification URL, set it to `null`:

<CodeGroup>
  ```bash cURL theme={null}
  curl -s -X PATCH "https://api.zapier.com/trigger-inbox/api/v1/inboxes/$INBOX_ID" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"notification_url": null}' \
    | python3 -m json.tool
  ```

  ```typescript TypeScript theme={null}
  await fetch(`https://api.zapier.com/trigger-inbox/api/v1/inboxes/${INBOX_ID}`, {
    method: "PATCH",
    headers: {
      Authorization: `Bearer ${TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ notification_url: null }),
  });
  ```

  ```python Python theme={null}
  requests.patch(
      f"https://api.zapier.com/trigger-inbox/api/v1/inboxes/{INBOX_ID}",
      json={"notification_url": None},
      headers=headers,
  ).raise_for_status()
  ```
</CodeGroup>

The `notification_url` is an optional endpoint on your server. When set, Zapier sends a POST request to that URL when new messages arrive, so your service can lease on demand instead of running a continuous polling loop.

The POST body contains only the inbox ID and a message count:

```json theme={null}
{
  "inbox_id": "your-inbox-id",
  "received_message_count": 3
}
```

The notification is a signal to trigger leasing — it does not contain message payloads. On receiving it, call the lease endpoint to retrieve the messages.

**Delivery behavior:** Transient failures (5xx responses, connection errors, timeouts) are retried automatically. Permanent failures (4xx responses) are not retried. Your endpoint must respond within 5 seconds.

## Delete an inbox

Deleting an inbox permanently removes it and cancels the underlying trigger subscription. Use this when you are decommissioning a service, cleaning up test inboxes, or need to change subscription settings that cannot be updated via PATCH.

<CodeGroup>
  ```bash cURL theme={null}
  curl -s -X DELETE "https://api.zapier.com/trigger-inbox/api/v1/inboxes/$INBOX_ID" \
    -H "Authorization: Bearer $TOKEN" | python3 -m json.tool
  ```

  ```typescript TypeScript theme={null}
  await fetch(`https://api.zapier.com/trigger-inbox/api/v1/inboxes/${INBOX_ID}`, {
    method: "DELETE",
    headers: { Authorization: `Bearer ${TOKEN}` },
  });
  ```

  ```python Python theme={null}
  requests.delete(
      f"https://api.zapier.com/trigger-inbox/api/v1/inboxes/{INBOX_ID}",
      headers=headers,
  ).raise_for_status()
  ```
</CodeGroup>

The response shows `status` set to `"deleting"` and `name` cleared to `null`. Deletion is asynchronous. The inbox remains visible in list calls with `status: "deleting"` until the process completes, which can take several hours. Go to [inbox states](/white-label/trigger-inbox/what-is-trigger-inbox-api#inbox-states) for an overview of all status transitions.

Once fully deleted, a GET request for that inbox returns `404 Not Found`.

**Pause vs delete:** If you might need the inbox again, pause it. Paused inboxes preserve your configuration and resume faster than creating a new one. Delete only when you are certain you no longer need the inbox.

## Production polling pattern

In production, the core loop runs continuously on an existing inbox. Lease available messages, process them, acknowledge on success, and repeat.

```bash theme={null}
#!/usr/bin/env bash
# Production polling loop — lease, process, acknowledge, repeat.
# Prerequisites: TOKEN and INBOX_ID already set.

BASE_URL="https://api.zapier.com/trigger-inbox/api/v1"

while true; do
  LEASE_RESPONSE=$(curl -s -X POST "$BASE_URL/inboxes/$INBOX_ID/messages/lease" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"lease_seconds": 300, "lease_limit": 10}')

  LEASE_ID=$(echo "$LEASE_RESPONSE" \
    | python3 -c "import sys,json; print(json.load(sys.stdin).get('lease_id') or '')" 2>/dev/null)

  if [ -n "$LEASE_ID" ]; then
    echo "Processing batch $LEASE_ID..."

    # Add your processing logic here.
    # On success, acknowledge. On failure, let the lease expire.
    # Messages return to the queue automatically.

    curl -s -X POST "$BASE_URL/inboxes/$INBOX_ID/messages/ack" \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d "{\"lease_id\": \"$LEASE_ID\"}"
  fi

  sleep 10
done
```

## Next steps

* [Consuming messages](/white-label/trigger-inbox/consuming-messages).
* [Trigger Inbox API errors](/white-label/trigger-inbox/errors).
* [Trigger Inbox API reference](/white-label/api-reference/inboxes/list-inboxes).