---
title: "Create Polling Webhook"
method: POST
path: "/v0/webhooks/polling"
tags: ["webhooks > polling"]
---

# Create Polling Webhook

`POST /v0/webhooks/polling`

## Request

- Base URL: `https://api.agentmail.to`
- URL: `https://api.agentmail.to/v0/webhooks/polling`
- Auth: HTTP bearer

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:**
```bash
agentmail webhooks polling create --client-id my-agent --event-types message.received
```

## Request body

- WebhooksPollingCreatePollingWebhookRequest
  - `client_id` string, required: Client ID of webhook.
  - `event_types` EventsEventType[], required: Event types for which to send events.
  - `inbox_ids` string[]: Inboxes for which to send events.
  - `pod_ids` string[]: Pods for which to send events.

## Response `200`

Response with status 200

- WebhooksPollingCreatePollingWebhookResponse: The subscription plus the one-time `token` that reads it.
  - `webhook_id` string, required: ID of webhook.
  - `client_id` string, required: Client ID of webhook.
  - `event_types` EventsEventType[], required: Event types for which to send events.
  - `pod_ids` string[]: Pods for which to send events.
  - `inbox_ids` string[]: Inboxes for which to send events.
  - `pod_id` string: 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`.
  - `inbox_id` string: 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`.
  - `updated_at` string, date-time, required: Time at which the subscription was last updated.
  - `created_at` string, date-time, required: Time at which the subscription was created.
  - `token` string, required: 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.

## Other responses

- `400`: Error response with status 400
- `409`: Error response with status 409

## Changes

- **2026-10-16** `3f5c7830c952`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/agentmail-to/apis/api/changes/v0/webhooks/polling/post.md)

---

[API](https://skmtc.dev/agentmail-to/apis/api.md) - [All operations](https://skmtc.dev/agentmail-to/apis/api/llms.txt) - [OpenAPI document](https://skmtc.dev/agentmail-to/apis/api/revisions/a9792efe7bdf?raw)