Manage your inbox

Once your trigger inbox 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:

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 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.

curl -s -X POST "https://api.zapier.com/trigger-inbox/v1/inboxes/$INBOX_ID/pause" \
  -H "Authorization: Bearer $TOKEN" | python3 -m json.tool

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

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

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

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.

Resume a paused inbox

Resuming restarts event collection. The inbox goes back through initializing before becoming active again.

curl -s -X POST "https://api.zapier.com/trigger-inbox/v1/inboxes/$INBOX_ID/resume" \
  -H "Authorization: Bearer $TOKEN" | python3 -m json.tool

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

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

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.

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. Check the paused_reason on a paused inbox:

curl -s "https://api.zapier.com/trigger-inbox/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'))"

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

resp = requests.get(
    f"https://api.zapier.com/trigger-inbox/v1/inboxes/{INBOX_ID}",
    headers=headers,
)
inbox = resp.json()
print(inbox["status"], inbox.get("paused_reason"))

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:

curl -s -X PATCH "https://api.zapier.com/trigger-inbox/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

await fetch(`https://api.zapier.com/trigger-inbox/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",
  }),
});

requests.patch(
    f"https://api.zapier.com/trigger-inbox/v1/inboxes/{INBOX_ID}",
    json={"notification_url": "https://your-server.example.com/inbox-webhook"},
    headers=headers,
).raise_for_status()

To remove the notification URL, set it to null:

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

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

requests.patch(
    f"https://api.zapier.com/trigger-inbox/v1/inboxes/{INBOX_ID}",
    json={"notification_url": None},
    headers=headers,
).raise_for_status()

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:

{
  "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.

curl -s -X DELETE "https://api.zapier.com/trigger-inbox/v1/inboxes/$INBOX_ID" \
  -H "Authorization: Bearer $TOKEN" | python3 -m json.tool

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

requests.delete(
    f"https://api.zapier.com/trigger-inbox/v1/inboxes/{INBOX_ID}",
    headers=headers,
).raise_for_status()

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 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.

#!/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/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.
To preview the fields your inbox produces, go to Preview the data your inbox will produce.
Trigger Inbox API errors.
Trigger Inbox API reference.

​Manage your inbox

​Pause an inbox

​Resume a paused inbox

​Handle an inbox paused by Zapier

​Update inbox settings

​Delete an inbox

​Production polling pattern

​Next steps

Manage your inbox

Pause an inbox

Resume a paused inbox

Handle an inbox paused by Zapier

Update inbox settings

Delete an inbox

Production polling pattern

Next steps