AgentMail inboxes > webhooks API

The inboxes > webhooks API from AgentMail — 2 operation(s) for inboxes > webhooks.

GitHub OpenAPI
Business capability
Webhook & Event Subscription Management BC-4270.80

Operations 7

GET /v0/inboxes/{inbox_id}/webhooks List Webhooks #
POST /v0/inboxes/{inbox_id}/webhooks Create Webhook #
GET /v0/inboxes/{inbox_id}/webhooks/{webhook_id} Get Webhook #
PATCH /v0/inboxes/{inbox_id}/webhooks/{webhook_id} Update Webhook #
DELETE /v0/inboxes/{inbox_id}/webhooks/{webhook_id} Delete Webhook #
GET /v0/inboxes/{inbox_id}/webhooks/{webhook_id}/headers Get Webhook Headers #
PATCH /v0/inboxes/{inbox_id}/webhooks/{webhook_id}/headers Update Webhook Headers #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • 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.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/agentmail:agentmail-inboxes-webhooks-api"
All apis
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.

Get an API 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 Specification

agentmail-inboxes-webhooks-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Reference inboxes > 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: inboxes > webhooks
paths:
  /v0/inboxes/{inbox_id}/webhooks:
    get:
      operationId: inboxes_webhooks_list
      summary: List Webhooks
      description: '**CLI:**

        ```bash

        agentmail inboxes webhooks list --inbox-id

        ```'
      tags:
      - inboxes > webhooks
      parameters:
      - name: inbox_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/inboxes_InboxId'
      - 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: inboxes_webhooks_create
      summary: Create Webhook
      description: 'Create a webhook scoped to this inbox.


        **CLI:**

        ```bash

        agentmail inboxes webhooks create --inbox-id --url https://example.com/webhook --event-types message.received

        ```'
      tags:
      - inboxes > webhooks
      parameters:
      - name: inbox_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/inboxes_InboxId'
      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_CreateInboxWebhookRequest'
      security:
      - Bearer: []
  /v0/inboxes/{inbox_id}/webhooks/{webhook_id}:
    get:
      operationId: inboxes_webhooks_get
      summary: Get Webhook
      description: '**CLI:**

        ```bash

        agentmail inboxes webhooks get --inbox-id --webhook-id

        ```'
      tags:
      - inboxes > webhooks
      parameters:
      - name: inbox_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/inboxes_InboxId'
      - 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: inboxes_webhooks_update
      summary: Update Webhook
      description: '**CLI:**

        ```bash

        agentmail inboxes webhooks update --inbox-id --webhook-id --event-types message.received

        ```'
      tags:
      - inboxes > webhooks
      parameters:
      - name: inbox_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/inboxes_InboxId'
      - 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_UpdateInboxWebhookRequest'
      security:
      - Bearer: []
    delete:
      operationId: inboxes_webhooks_delete
      summary: Delete Webhook
      description: '**CLI:**

        ```bash

        agentmail inboxes webhooks delete --inbox-id --webhook-id

        ```'
      tags:
      - inboxes > webhooks
      parameters:
      - name: inbox_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/inboxes_InboxId'
      - 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/inboxes/{inbox_id}/webhooks/{webhook_id}/headers:
    get:
      operationId: inboxes_webhooks_getHeaders
      summary: Get Webhook Headers
      description: 'List the names of custom HTTP headers included with deliveries to this inbox-scoped webhook.

        Header values are write-only and are never returned.'
      tags:
      - inboxes > webhooks
      parameters:
      - name: inbox_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/inboxes_InboxId'
      - 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: inboxes_webhooks_updateHeaders
      summary: Update Webhook Headers
      description: 'Atomically set, replace, or remove custom HTTP headers included with deliveries to this

        inbox-scoped webhook. Header values remain write-only.'
      tags:
      - inboxes > webhooks
      parameters:
      - name: inbox_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/inboxes_InboxId'
      - 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_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_UpdateInboxWebhookRequest:
      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.'
      description: 'Update an inbox-scoped webhook. It is fixed to its inbox, so only `event_types` and `enabled` can

        change.'
      title: UpdateInboxWebhookRequest
    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_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
    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
    webhooks_CreateInboxWebhookRequest:
      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'
      required:
      - url
      - event_types
      description: 'Create a webhook scoped to an inbox. The inbox comes from the path, so `inbox_ids` and `pod_ids`

        are not accepted.'
      title: CreateInboxWebhookRequest
    events_PodIds:
      type: array
      items:
        type: string
      description: Pods for which to send events.
      title: PodIds
    ErrorMessage:
      type: string
      description: Error message.
      title: ErrorMessage
    inboxes_InboxId:
      type: string
      description: The ID of the inbox.
      title: InboxId
    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
    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)