Skip to main content

​
Consuming messages

Once your trigger inbox is active, you work with messages through four operations: lease, acknowledge, release, and list. This page explains each operation, their parameters, and how to handle edge cases like quarantined messages and possible duplicates.

​
Lease messages

Leasing claims a batch of available messages and gives your app exclusive access for a set duration. No other consumer can claim the same messages while they are leased. If you do not acknowledge before the lease expires, the messages return to the queue automatically. 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}"}

curl -s -X POST "https://api.zapier.com/trigger-inbox/api/v1/inboxes/$INBOX_ID/messages/lease" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"lease_seconds": 300, "lease_limit": 10}' | python3 -m json.tool

​
Request parameters

ParameterTypeDefaultMaxDescription
lease_secondsinteger3003600How long, in seconds, to hold the lease. Messages return to the queue if not acknowledged within this window.
lease_limitinteger10100Maximum number of messages to lease in one call.

​
Response fields

FieldDescription
lease_idUnique identifier for the lease batch. Required for acknowledge and release. null if no messages are available.
leased_untilISO 8601 timestamp when the lease expires. null if no messages are available.
results[]Array of leased messages. Empty if no messages are available.
results[].idUnique message identifier.
results[].created_atWhen the message was queued.
results[].status"leased" while held, transitions to "acked" after acknowledgment.
results[].payloadThe event data from the connected app.
results[].message_attributes.lease_countNumber of times this message has been leased. Increases each time a lease expires or is released.
results[].message_attributes.error_messageError from the data hydration step, if one occurred. The message is still delivered. Check this field before processing.
results[].message_attributes.possible_duplicate_datatrue if Zapier detected a potential duplicate due to a deduplication key change.
inbox_attributes.statusCurrent inbox status at the time of the lease call.
inbox_attributes.paused_reasonSet if the inbox is paused.

​
Empty queue

When no messages are available, the API returns HTTP 200 with lease_id: null and results: []. 
{
  "lease_id": null,
  "leased_until": null,
  "results": [],
  "inbox_attributes": {
    "status": "active",
    "paused_reason": null
  }
}
Continue polling on a 200 response. This is the normal idle state between events.

​
Paused and drained (409)

If the inbox is paused and all buffered messages have been consumed, the API returns HTTP 409: 
{
  "detail": "Inbox is paused and fully drained.",
  "inbox_attributes": {
    "status": "paused",
    "paused_reason": "authentication",
    "paused_at": "2026-03-12T16:59:47.185Z"
  }
}
Check inbox_attributes.paused_reason to determine the appropriate action. For authentication or authentication_access_revoked, the connected app account needs to be reconnected. For other reasons, go to Manage your inbox for the full list of actions.
A 409 response means the inbox is paused and empty. If messages are still available in a paused inbox, leasing continues to return them with HTTP 201 until the queue drains.

​
Acknowledge messages

Acknowledging permanently removes messages from the inbox. Only acknowledge after your processing succeeds.

​
Acknowledge a full batch

Pass the lease_id to acknowledge all messages in the lease: 
curl -s -X POST "https://api.zapier.com/trigger-inbox/api/v1/inboxes/$INBOX_ID/messages/ack" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"lease_id": "'"$LEASE_ID"'"}' | python3 -m json.tool
A successful response returns HTTP 201 with each acknowledged message showing "status": "acked".

​
Acknowledge specific messages

To acknowledge a subset of the leased batch, include message_ids: 
curl -s -X POST "https://api.zapier.com/trigger-inbox/api/v1/inboxes/$INBOX_ID/messages/ack" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "lease_id": "'"$LEASE_ID"'",
    "message_ids": ["'"$MESSAGE_ID_1"'", "'"$MESSAGE_ID_2"'"]
  }' | python3 -m json.tool
Non-acknowledged messages in the same lease remain leased until the lease expires, then return to the queue for retry.

​
Expired leases

If the lease has expired when you call acknowledge, the API returns an error. Messages that have been leased and returned to the queue 5 times without acknowledgment are quarantined automatically. Check Handle quarantined messages for next steps.
The Trigger Inbox API uses at-least-once delivery. Build idempotent processing and check the message id before acting on a payload.

​
Release messages

Releasing immediately returns leased messages to the queue without acknowledging them. Use release when your processing has failed and you want to make the messages available again without waiting for the lease to expire. 
curl -s -X POST "https://api.zapier.com/trigger-inbox/api/v1/inboxes/$INBOX_ID/messages/release" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"lease_id": "'"$LEASE_ID"'"}' | python3 -m json.tool
Released messages return with "status": "available" in the response. To release specific messages within a lease, include message_ids, using the same pattern as partial acknowledgment.
Release counts as an attempt. Each release increments lease_count toward the quarantine threshold of 5. If you expect repeated failures on a message, investigate before releasing again rather than looping.
Release vs. letting the lease expire: Use release when you want messages available immediately for another consumer or for a retry. Let the lease expire when you prefer a delay before retry, for example to back off from a downstream service that is temporarily unavailable.

​
List messages

To inspect the current state of your inbox, including quarantined messages and messages with errors, use the list endpoint: 
curl -s "https://api.zapier.com/trigger-inbox/api/v1/inboxes/$INBOX_ID/messages" \
  -H "Authorization: Bearer $TOKEN" | python3 -m json.tool
Results are paginated using cursor-based pagination. Use the next link from the response to retrieve the next page. List results include messages in all states: available, leased, acked, and quarantined.
List results do not include message payloads. Use leasing to retrieve payloads.

​
Handle quarantined messages

A quarantined message is no longer returned by lease calls but remains visible in list calls for inspection. To find quarantined messages, list messages and filter by status: 
curl -s "https://api.zapier.com/trigger-inbox/api/v1/inboxes/$INBOX_ID/messages" \
  -H "Authorization: Bearer $TOKEN" \
  | python3 -c "
import sys, json
msgs = json.load(sys.stdin)['results']
quarantined = [m for m in msgs if m['status'] == 'quarantined']
print(json.dumps(quarantined, indent=2))
"
A message is quarantined after it is leased 5 times without being acknowledged, so the cause is almost always on the consuming side: your processing repeatedly fails before it can acknowledge the message. To investigate, check message_attributes.error_message and your application logs from around the lease attempts. Fix the processing issue so future messages are acknowledged normally. Quarantined messages are not automatically removed and are not redelivered. They remain visible in list calls for inspection (metadata only, not the payload).

​
Handle error messages and possible duplicates

​
Error messages

When Zapier encounters a problem fetching full event data from the connected app, it still delivers the message with a partial payload. Check message_attributes.error_message before processing: 
{
  "id": "019ce2fe-5ed1-7318-8a60-33dffd911f6b",
  "status": "leased",
  "payload": { "key": "value" },
  "message_attributes": {
    "lease_count": 1,
    "error_message": "Your Slack account on Zapier is expired/invalid. Please reconnect it to fix this.",
    "possible_duplicate_data": false
  }
}
If error_message is set, the payload may be incomplete. Acknowledge the message to remove it from the queue, or release it if you want to retry after addressing the underlying issue (for example, reconnecting the app account). For API-level errors and inbox lifecycle failures, go to Trigger Inbox errors.

​
Possible duplicates

When possible_duplicate_data is true, the message may contain event data that was already delivered under a different deduplication key. This can occur after a trigger updates how it identifies unique events. Apply your own deduplication logic when this flag is set. For example, check a unique field in the payload against your data store before writing.

​
Next steps