openapi: 3.1.0
info:
  title: API Reference agent 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: webhooks
paths:
  /v0/webhooks:
    get:
      operationId: list
      summary: List Webhooks
      description: '**CLI:**

        ```bash

        agentmail webhooks list

        ```'
      tags:
      - webhooks
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_:Limit'
      - name: page_token
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_:PageToken'
      - name: ascending
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_:Ascending'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_webhooks:ListWebhooksResponse'
    post:
      operationId: create
      summary: Create Webhook
      description: '**CLI:**

        ```bash

        agentmail webhooks create --url https://example.com/webhook --event-type message.received

        ```'
      tags:
      - webhooks
      parameters:
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_webhooks:Webhook'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:ValidationErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_webhooks:CreateWebhookRequest'
  /v0/webhooks/{webhook_id}:
    get:
      operationId: get
      summary: Get Webhook
      description: '**CLI:**

        ```bash

        agentmail webhooks get --webhook-id <webhook_id>

        ```'
      tags:
      - webhooks
      parameters:
      - name: webhook_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/type_webhooks:WebhookId'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_webhooks:Webhook'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:ErrorResponse'
    patch:
      operationId: update
      summary: Update Webhook
      description: 'Update inbox or pod subscriptions, or replace the webhook''s `event_types` in full when you pass a

        non-empty `event_types` array (see request field docs). Inbox and pod changes use add/remove lists.


        **CLI:**

        ```bash

        agentmail webhooks update --webhook-id <webhook_id> --add-inbox-id <inbox_id>

        ```'
      tags:
      - webhooks
      parameters:
      - name: webhook_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/type_webhooks:WebhookId'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_webhooks:Webhook'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:ValidationErrorResponse'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_webhooks:UpdateWebhookRequest'
    delete:
      operationId: delete
      summary: Delete Webhook
      description: '**CLI:**

        ```bash

        agentmail webhooks delete --webhook-id <webhook_id>

        ```'
      tags:
      - webhooks
      parameters:
      - name: webhook_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/type_webhooks:WebhookId'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:ErrorResponse'
components:
  schemas:
    type_webhooks:UpdateWebhookRequest:
      type: object
      properties:
        event_types:
          $ref: '#/components/schemas/type_webhooks:UpdateWebhookEventTypes'
        add_inbox_ids:
          $ref: '#/components/schemas/type_events:InboxIds'
          description: Inbox IDs to subscribe to the webhook.
        remove_inbox_ids:
          $ref: '#/components/schemas/type_events:InboxIds'
          description: Inbox IDs to unsubscribe from the webhook.
        add_pod_ids:
          $ref: '#/components/schemas/type_events:PodIds'
          description: Pod IDs to subscribe to the webhook.
        remove_pod_ids:
          $ref: '#/components/schemas/type_events:PodIds'
          description: Pod IDs to unsubscribe from the webhook.
      title: UpdateWebhookRequest
    type_webhooks:ListWebhooksResponse:
      type: object
      properties:
        count:
          $ref: '#/components/schemas/type_:Count'
        limit:
          $ref: '#/components/schemas/type_:Limit'
        next_page_token:
          $ref: '#/components/schemas/type_:PageToken'
        webhooks:
          type: array
          items:
            $ref: '#/components/schemas/type_webhooks:Webhook'
          description: Ordered by `created_at` descending.
      required:
      - count
      - webhooks
      title: ListWebhooksResponse
    type_:Count:
      type: integer
      description: Number of items returned.
      title: Count
    type_webhooks:CreateWebhookRequest:
      type: object
      properties:
        url:
          $ref: '#/components/schemas/type_webhooks:Url'
        event_types:
          $ref: '#/components/schemas/type_webhooks:CreateWebhookEventTypes'
        client_id:
          $ref: '#/components/schemas/type_webhooks:ClientId'
        inbox_ids:
          $ref: '#/components/schemas/type_events:InboxIds'
        pod_ids:
          $ref: '#/components/schemas/type_events:PodIds'
      required:
      - url
      - event_types
      title: CreateWebhookRequest
    type_webhooks:CreateWebhookEventTypes:
      $ref: '#/components/schemas/type_events:EventTypes'
      description: '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](https://docs.agentmail.to/webhooks-overview)

        for spam, blocked, and unauthenticated events and required permissions.'
      title: CreateWebhookEventTypes
    type_: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
    type_webhooks:UpdateWebhookEventTypes:
      $ref: '#/components/schemas/type_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 or send an empty array to leave event types unchanged. Clearing all types with an empty

        list is not supported. Subscribing to `message.received.spam`, `message.received.blocked`, or

        `message.received.unauthenticated` requires the matching label permission on the API key.'
      title: UpdateWebhookEventTypes
    type_events:EventType:
      type: string
      enum:
      - message.received
      - message.received.spam
      - message.received.blocked
      - message.received.unauthenticated
      - message.sent
      - message.delivered
      - message.bounced
      - message.complained
      - message.rejected
      - domain.verified
      title: EventType
    type_webhooks:Url:
      type: string
      description: URL of webhook endpoint.
      title: Url
    type_events:InboxIds:
      type: array
      items:
        type: string
      description: Inboxes for which to send events. Maximum 10 per webhook.
      title: InboxIds
    type_:ValidationErrorResponse:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/type_:ErrorName'
        code:
          $ref: '#/components/schemas/type_:ErrorCode'
        message:
          $ref: '#/components/schemas/type_:ErrorMessage'
        errors:
          description: Validation errors. Each entry has a path and a message identifying the invalid field.
        fix:
          $ref: '#/components/schemas/type_:ErrorFix'
        docs:
          $ref: '#/components/schemas/type_:ErrorDocs'
      required:
      - name
      - errors
      title: ValidationErrorResponse
    type_events:PodIds:
      type: array
      items:
        type: string
      description: Pods for which to send events. Maximum 10 per webhook.
      title: PodIds
    type_:ErrorFix:
      type: string
      description: The concrete next action that resolves the error.
      title: ErrorFix
    type_:ErrorMessage:
      type: string
      description: Error message.
      title: ErrorMessage
    type_:Limit:
      type: integer
      description: Limit of number of items returned.
      title: Limit
    type_events:EventTypes:
      type: array
      items:
        $ref: '#/components/schemas/type_events:EventType'
      description: Event types for which to send events.
      title: EventTypes
    type_:PageToken:
      type: string
      description: Page token for pagination.
      title: PageToken
    type_:ErrorName:
      type: string
      description: Name of error.
      title: ErrorName
    type_:ErrorDocs:
      type: string
      description: Link to the error reference entry for this code.
      title: ErrorDocs
    type_:ErrorResponse:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/type_:ErrorName'
        code:
          $ref: '#/components/schemas/type_:ErrorCode'
        message:
          $ref: '#/components/schemas/type_:ErrorMessage'
        fix:
          $ref: '#/components/schemas/type_:ErrorFix'
        docs:
          $ref: '#/components/schemas/type_:ErrorDocs'
      required:
      - name
      - message
      title: ErrorResponse
    type_webhooks:WebhookId:
      type: string
      description: ID of webhook.
      title: WebhookId
    type_webhooks:Webhook:
      type: object
      properties:
        webhook_id:
          $ref: '#/components/schemas/type_webhooks:WebhookId'
        url:
          $ref: '#/components/schemas/type_webhooks:Url'
        event_types:
          $ref: '#/components/schemas/type_events:EventTypes'
        pod_ids:
          $ref: '#/components/schemas/type_events:PodIds'
        inbox_ids:
          $ref: '#/components/schemas/type_events:InboxIds'
        secret:
          type: string
          description: Secret for webhook signature verification.
        enabled:
          type: boolean
          description: Webhook is enabled.
        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/type_webhooks:ClientId'
      required:
      - webhook_id
      - url
      - secret
      - enabled
      - updated_at
      - created_at
      title: Webhook
    type_:Ascending:
      type: boolean
      description: Sort in ascending temporal order.
      title: Ascending
    type_webhooks:ClientId:
      type: string
      description: Client ID of webhook.
      title: ClientId
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer