Skip to main content

​
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/api/v1/inboxes/$INBOX_ID/pause" \
  -H "Authorization: Bearer $TOKEN" | python3 -m json.tool
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/api/v1/inboxes/$INBOX_ID/resume" \
  -H "Authorization: Bearer $TOKEN" | python3 -m json.tool
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/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'))"
Paused reasonWhat it meansRecommended action
userYou paused the inbox manuallyResume when ready
authenticationThe connected app account credentials are invalid or expiredReconnect the app account, then resume
authentication_access_revokedAccess to the connected app was revoked, often because a shared connection was unsharedReconnect the app account, then resume
partner_revokedThe app developer or Zapier partner revoked the integration’s accessContact Zapier support
subscribe_failedThe trigger subscription could not be establishedDelete and recreate the inbox; if it persists, contact Zapier support
migrate_failedAn internal migration failedContact Zapier support
abandonedThe inbox has not been used for an extended periodResume if still needed, or delete
upstream_failuresThe connected app is returning errorsWait and retry; if persistent, check the app’s status page
unknownAn unclassified error occurredContact 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/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
To remove the notification URL, set it to 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
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/api/v1/inboxes/$INBOX_ID" \
  -H "Authorization: Bearer $TOKEN" | python3 -m json.tool
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/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