AgentMail pods > webhooks API
The pods > webhooks API from AgentMail — 2 operation(s) for pods > webhooks.
The pods > webhooks API from AgentMail — 2 operation(s) for pods > webhooks.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/agentmail:agentmail-pods-webhooks-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Reference pods > webhooks API
version: 1.0.0
servers:
- url: https://api.agentmail.to
description: prod
- url: https://x402.api.agentmail.to
description: prod-x402
- url: https://mpp.api.agentmail.to
description: prod-mpp
- url: https://api.agentmail.eu
description: eu-prod
tags:
- name: pods > webhooks
paths:
/v0/pods/{pod_id}/webhooks:
get:
operationId: pods_webhooks_list
summary: List Webhooks
description: '**CLI:**
```bash
agentmail pods webhooks list --pod-id
```'
tags:
- pods > webhooks
parameters:
- name: pod_id
in: path
required: true
schema:
$ref: '#/components/schemas/pods_PodId'
- name: limit
in: query
required: false
schema:
$ref: '#/components/schemas/Limit'
- name: page_token
in: query
required: false
schema:
$ref: '#/components/schemas/PageToken'
- name: ascending
in: query
required: false
schema:
$ref: '#/components/schemas/Ascending'
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/webhooks_ListWebhooksResponse'
security:
- Bearer: []
post:
operationId: pods_webhooks_create
summary: Create Webhook
description: 'Create a webhook scoped to this pod.
**CLI:**
```bash
agentmail pods webhooks create --pod-id --url https://example.com/webhook --event-types message.received
```'
tags:
- pods > webhooks
parameters:
- name: pod_id
in: path
required: true
schema:
$ref: '#/components/schemas/pods_PodId'
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/webhooks_Webhook'
'400':
description: Error response with status 400
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationErrorResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/webhooks_CreatePodWebhookRequest'
security:
- Bearer: []
/v0/pods/{pod_id}/webhooks/{webhook_id}:
get:
operationId: pods_webhooks_get
summary: Get Webhook
description: '**CLI:**
```bash
agentmail pods webhooks get --pod-id --webhook-id
```'
tags:
- pods > webhooks
parameters:
- name: pod_id
in: path
required: true
schema:
$ref: '#/components/schemas/pods_PodId'
- name: webhook_id
in: path
required: true
schema:
$ref: '#/components/schemas/webhooks_WebhookId'
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/webhooks_Webhook'
'404':
description: Error response with status 404
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- Bearer: []
patch:
operationId: pods_webhooks_update
summary: Update Webhook
description: '**CLI:**
```bash
agentmail pods webhooks update --pod-id --webhook-id --add-inbox-ids
```'
tags:
- pods > webhooks
parameters:
- name: pod_id
in: path
required: true
schema:
$ref: '#/components/schemas/pods_PodId'
- name: webhook_id
in: path
required: true
schema:
$ref: '#/components/schemas/webhooks_WebhookId'
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/webhooks_Webhook'
'400':
description: Error response with status 400
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationErrorResponse'
'404':
description: Error response with status 404
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/webhooks_UpdatePodWebhookRequest'
security:
- Bearer: []
delete:
operationId: pods_webhooks_delete
summary: Delete Webhook
description: '**CLI:**
```bash
agentmail pods webhooks delete --pod-id --webhook-id
```'
tags:
- pods > webhooks
parameters:
- name: pod_id
in: path
required: true
schema:
$ref: '#/components/schemas/pods_PodId'
- name: webhook_id
in: path
required: true
schema:
$ref: '#/components/schemas/webhooks_WebhookId'
responses:
'200':
description: Successful response
'404':
description: Error response with status 404
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- Bearer: []
/v0/pods/{pod_id}/webhooks/{webhook_id}/headers:
get:
operationId: pods_webhooks_getHeaders
summary: Get Webhook Headers
description: 'List the names of custom HTTP headers included with deliveries to this pod-scoped webhook.
Header values are write-only and are never returned.'
tags:
- pods > webhooks
parameters:
- name: pod_id
in: path
required: true
schema:
$ref: '#/components/schemas/pods_PodId'
- name: webhook_id
in: path
required: true
schema:
$ref: '#/components/schemas/webhooks_WebhookId'
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/webhooks_WebhookHeaderNamesResponse'
'404':
description: Error response with status 404
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- Bearer: []
patch:
operationId: pods_webhooks_updateHeaders
summary: Update Webhook Headers
description: 'Atomically set, replace, or remove custom HTTP headers included with deliveries to this
pod-scoped webhook. Header values remain write-only.'
tags:
- pods > webhooks
parameters:
- name: pod_id
in: path
required: true
schema:
$ref: '#/components/schemas/pods_PodId'
- name: webhook_id
in: path
required: true
schema:
$ref: '#/components/schemas/webhooks_WebhookId'
responses:
'204':
description: Response with status 204
content:
application/json:
schema:
type: object
properties: {}
'400':
description: Error response with status 400
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationErrorResponse'
'404':
description: Error response with status 404
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/webhooks_UpdateWebhookHeadersRequest'
security:
- Bearer: []
components:
schemas:
webhooks_WebhookId:
type: string
description: ID of webhook.
title: WebhookId
ErrorCode:
type: string
description: Stable, machine-readable error code in snake_case (for example, not_found or missing_permission). Branch on this rather than the message text.
title: ErrorCode
webhooks_CreatePodWebhookRequest:
type: object
properties:
url:
$ref: '#/components/schemas/webhooks_Url'
event_types:
$ref: '#/components/schemas/webhooks_CreateWebhookEventTypes'
client_id:
$ref: '#/components/schemas/webhooks_ClientId'
headers:
$ref: '#/components/schemas/webhooks_WebhookHeaders'
inbox_ids:
$ref: '#/components/schemas/events_InboxIds'
description: 'Inboxes for which to send events. A webhook can list at most 10 inboxes and pods combined;
more returns `403` with `limit_exceeded`.'
required:
- url
- event_types
description: 'Create a webhook scoped to a pod. The pod comes from the path, so `pod_ids` is not accepted.
Optionally pass `inbox_ids` to narrow the webhook to specific inboxes within the pod; omit to
receive events for the whole pod.'
title: CreatePodWebhookRequest
pods_PodId:
type: string
description: ID of pod.
title: PodId
webhooks_ClientId:
type: string
description: Client ID of webhook.
title: ClientId
webhooks_Webhook:
type: object
properties:
webhook_id:
$ref: '#/components/schemas/webhooks_WebhookId'
url:
$ref: '#/components/schemas/webhooks_Url'
event_types:
$ref: '#/components/schemas/events_EventTypes'
pod_ids:
$ref: '#/components/schemas/events_PodIds'
inbox_ids:
$ref: '#/components/schemas/events_InboxIds'
pod_id:
type: string
description: 'ID of the pod the webhook belongs to: the pod it was created in, or the pod of the inbox it
belongs to. Absent for an organization webhook and on some inbox webhooks. This is not the
list of pods it receives events for; see `pod_ids`.'
inbox_id:
type: string
description: 'ID of the inbox the webhook belongs to, if it was created for an inbox. This is not the list
of inboxes it receives events for; see `inbox_ids`.'
secret:
type: string
description: Secret for webhook signature verification.
enabled:
type: boolean
description: 'Whether the webhook is enabled. It becomes false when you disable it, and also when deliveries to
the URL have failed for 5 days, in which case AgentMail sends no notification. Re-enable it with
update and `enabled` set to true.'
updated_at:
type: string
format: date-time
description: Time at which webhook was last updated.
created_at:
type: string
format: date-time
description: Time at which webhook was created.
client_id:
$ref: '#/components/schemas/webhooks_ClientId'
required:
- webhook_id
- url
- secret
- enabled
- updated_at
- created_at
title: Webhook
Count:
type: integer
description: Number of items returned.
title: Count
webhooks_CreateWebhookEventTypes:
$ref: '#/components/schemas/events_EventTypes'
description: 'Full list of event types this webhook should receive. Required: omitting it or sending an empty array
returns a `400`, and there is no "all events" default. Send every type you want in this array (not
incremental). See [Webhooks overview](https://docs.agentmail.to/webhooks-overview)
for spam, blocked, and unauthenticated events and required permissions.'
title: CreateWebhookEventTypes
ValidationErrorResponse:
type: object
properties:
name:
$ref: '#/components/schemas/ErrorName'
code:
$ref: '#/components/schemas/ErrorCode'
message:
$ref: '#/components/schemas/ErrorMessage'
errors:
description: Validation errors. Each entry has a path and a message identifying the invalid field.
fix:
$ref: '#/components/schemas/ErrorFix'
docs:
$ref: '#/components/schemas/ErrorDocs'
required:
- name
- errors
title: ValidationErrorResponse
webhooks_WebhookHeaderNamesResponse:
type: object
properties:
header_names:
type: array
items:
type: string
description: Names of the custom delivery headers configured for this webhook. Header values are never returned.
required:
- header_names
title: WebhookHeaderNamesResponse
webhooks_WebhookHeaders:
type: object
additionalProperties:
type: string
description: 'Custom HTTP headers to include with every delivery to this webhook. Header values are write-only:
AgentMail never returns them from webhook read endpoints. The map must contain at least one entry
when provided, and every name and value must be a valid HTTP header.'
title: WebhookHeaders
webhooks_Url:
type: string
description: URL of webhook endpoint.
title: Url
ErrorDocs:
type: string
description: Link to the error reference entry for this code.
title: ErrorDocs
webhooks_UpdateWebhookHeadersRequest:
type: object
properties:
headers:
$ref: '#/components/schemas/webhooks_WebhookHeaders'
remove_headers:
type: array
items:
type: string
description: Names of custom delivery headers to remove.
description: 'Set, replace, or remove custom delivery headers. Provide at least one of `headers` or
`remove_headers`. A header cannot be set and removed in the same request, regardless of casing.'
title: UpdateWebhookHeadersRequest
events_PodIds:
type: array
items:
type: string
description: Pods for which to send events.
title: PodIds
ErrorMessage:
type: string
description: Error message.
title: ErrorMessage
webhooks_ListWebhooksResponse:
type: object
properties:
count:
$ref: '#/components/schemas/Count'
limit:
$ref: '#/components/schemas/Limit'
next_page_token:
$ref: '#/components/schemas/PageToken'
webhooks:
type: array
items:
$ref: '#/components/schemas/webhooks_Webhook'
description: Ordered by `created_at` descending.
required:
- count
- webhooks
title: ListWebhooksResponse
events_InboxIds:
type: array
items:
type: string
description: Inboxes for which to send events.
title: InboxIds
webhooks_UpdateWebhookEventTypes:
$ref: '#/components/schemas/events_EventTypes'
description: 'When you send a non-empty list, it replaces the webhook''s subscribed event types in full (the same
"set the list" behavior as create). It is not a merge or diff: include every event type you want after
the update. Sending a one-element array means the webhook will only receive that one type afterward.
Omit this field to leave event types unchanged. An empty array is rejected with a `400`: a webhook
always has at least one event type. Subscribing to `message.received.spam`, `message.received.blocked`, or
`message.received.unauthenticated` requires the matching label permission on the API key.'
title: UpdateWebhookEventTypes
events_EventType:
type: string
enum:
- message.received
- message.received.spam
- message.received.blocked
- message.received.unauthenticated
- message.security.completed
- message.security.review
- message.security.override
- message.sent
- message.delivered
- message.bounced
- message.complained
- message.rejected
- message.opened
- domain.verified
- calendar.event.created
- calendar.event.updated
- calendar.event.deleted
- calendar.event.responded
- calendar.event.starting
- calendar.event.ending
title: EventType
ErrorFix:
type: string
description: The concrete next action that resolves the error.
title: ErrorFix
Limit:
type: integer
description: Limit of number of items returned.
title: Limit
Ascending:
type: boolean
description: Sort in ascending temporal order.
title: Ascending
ErrorName:
type: string
description: Name of error.
title: ErrorName
webhooks_UpdatePodWebhookRequest:
type: object
properties:
event_types:
$ref: '#/components/schemas/webhooks_UpdateWebhookEventTypes'
enabled:
type: boolean
description: 'Set to true to re-enable a webhook that was disabled after repeated failed deliveries, or false
to disable it. AgentMail does not notify you when a webhook is disabled automatically; check this
field when you get or list webhooks. Events that occurred while the webhook was disabled are not
redelivered. Re-enabling requires the read permission for every restricted event type the webhook
subscribes to: `label_spam_read`, `label_blocked_read`, or `label_unauthenticated_read` for the
received variants, `message_read` for `message.security.*`, and `calendar_event_read` for
`calendar.event.*`. A webhook with no event type filter is checked against all of them.'
add_inbox_ids:
$ref: '#/components/schemas/events_InboxIds'
description: 'Inbox IDs to subscribe to the webhook. This only adds to what the webhook receives: on a webhook
that covers its whole pod, it changes nothing. To receive only specific inboxes, create a webhook
with `inbox_ids` instead. The webhook can list at most 10 inboxes and pods combined after the
update.'
remove_inbox_ids:
$ref: '#/components/schemas/events_InboxIds'
description: Inbox IDs to unsubscribe from the webhook.
description: 'Update a pod-scoped webhook. You can adjust which inboxes within the pod it listens to, replace
its `event_types`, and set `enabled`, but not change the pod scope itself.'
title: UpdatePodWebhookRequest
PageToken:
type: string
description: Page token for pagination.
title: PageToken
events_EventTypes:
type: array
items:
$ref: '#/components/schemas/events_EventType'
description: Event types for which to send events.
title: EventTypes
ErrorResponse:
type: object
properties:
name:
$ref: '#/components/schemas/ErrorName'
code:
$ref: '#/components/schemas/ErrorCode'
message:
$ref: '#/components/schemas/ErrorMessage'
fix:
$ref: '#/components/schemas/ErrorFix'
docs:
$ref: '#/components/schemas/ErrorDocs'
required:
- name
- message
title: ErrorResponse
securitySchemes:
Bearer:
type: http
scheme: bearer
x-provenance:
method: harvested
publisher: AgentMail
source: https://docs.agentmail.to/openapi.json
note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
stamped by stamp-openapi-provenance.py (roadmap#793)