Skip to navigation
API ReferenceWebhooksPolling

Create Polling Webhook

Creates a subscription the agent polls for events, and returns the token that reads it. Each organization, pod, and inbox holds at most 10 polling webhooks; a repeat create with the same client_id re-issues the token of the existing one instead of counting against that limit.

CLI:

agentmail webhooks polling create --client-id my-agent --event-types message.received

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.
client_idstringRequired

Required. Idempotency key of the subscription: creating again with the same client_id through the same route returns the existing subscription with a fresh token instead of a second subscription, so a restarted agent resumes where it left off. Also accepted in place of webhook_id on get and delete.

event_typeslist of enumsRequired

Full list of event types this webhook should receive. At least one type is required. Send every type you want in this array (not incremental). See Webhooks overview for spam, blocked, and unauthenticated events and required permissions.

inbox_idslist of stringsOptional
Inboxes for which to send events. Maximum 10 per webhook.
pod_idslist of stringsOptional

Pods for which to receive events. Maximum 10 channels (pods plus inboxes) per subscription. The subscription receives an event that matches any listed pod or inbox, so a listed pod already covers every inbox in it.

Response

This endpoint returns an object.
client_idstring

Required. Idempotency key of the subscription: creating again with the same client_id through the same route returns the existing subscription with a fresh token instead of a second subscription, so a restarted agent resumes where it left off. Also accepted in place of webhook_id on get and delete.

created_atdatetime
Time at which the subscription was created.
event_typeslist of enums
Event types for which to send events.
tokenstring

Credential for reading this subscription’s events. Hand it to the Svix AutoConfig consumer (AutoConfigConsumer in the svix package for TypeScript and Python): receive returns the events queued since your last commit, commit marks them as processed. Returned by create only and never readable afterward. Create again with the same client_id to get a new token; the previous one stops working immediately.

updated_atdatetime
Time at which the subscription was last updated.
webhook_idstring
ID of webhook.
inbox_idstringOptional

ID of the inbox the subscription belongs to, if it was created for an inbox. This is not the list of inboxes it receives events for; see inbox_ids.

inbox_idslist of stringsOptional
Inboxes for which to send events. Maximum 10 per webhook.
pod_idstringOptional

ID of the pod the subscription belongs to: the pod it was created in, or the pod of the inbox it belongs to. Absent for an organization subscription. This is not the list of pods it receives events for; see pod_ids.

pod_idslist of stringsOptional
Pods for which to send events. Maximum 10 per webhook.

Errors

400
Validation Error
409
Conflict Error