AgentMail pods > webhooks API

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: list
      summary: List Webhooks
      description: '**CLI:**

        ```bash

        agentmail pods:webhooks list --pod-id <pod_id>

        ```'
      tags:
      - pods > webhooks
      parameters:
      - name: pod_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/type_pods_PodId'
      - 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: 'Create a webhook scoped to this pod.


        **CLI:**

        ```bash

        agentmail pods:webhooks create --pod-id <pod_id> --url https://example.com/webhook --event-type message.received

        ```'
      tags:
      - pods > webhooks
      parameters:
      - name: pod_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/type_pods_PodId'
      - 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_CreatePodWebhookRequest'
  /v0/pods/{pod_id}/webhooks/{webhook_id}:
    get:
      operationId: get
      summary: Get Webhook
      description: '**CLI:**

        ```bash

        agentmail pods:webhooks get --pod-id <pod_id> --webhook-id <webhook_id>

        ```'
      tags:
      - pods > webhooks
      parameters:
      - name: pod_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/type_pods_PodId'
      - 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: '**CLI:**

        ```bash

        agentmail pods:webhooks update --pod-id <pod_id> --webhook-id <webhook_id> --add-inbox-id <inbox_id>

        ```'
      tags:
      - pods > webhooks
      parameters:
      - name: pod_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/type_pods_PodId'
      - 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_UpdatePodWebhookRequest'
    delete:
      operationId: delete
      summary: Delete Webhook
      description: '**CLI:**

        ```bash

        agentmail pods:webhooks delete --pod-id <pod_id> --webhook-id <webhook_id>

        ```'
      tags:
      - pods > webhooks
      parameters:
      - name: pod_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/type_pods_PodId'
      - 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_events_EventTypes:
      type: array
      items:
        $ref: '#/components/schemas/type_events_EventType'
      description: Event types for which to send events.
      title: EventTypes
    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_webhooks_UpdatePodWebhookRequest:
      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.
      description: 'Update a pod-scoped webhook. You can adjust which inboxes within the pod it listens to and replace

        its `event_types`, but not the pod scope itself.'
      title: UpdatePodWebhookRequest
    type_webhooks_CreatePodWebhookRequest:
      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'
      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
    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_events_InboxIds:
      type: array
      items:
        type: string
      description: Inboxes for which to send events. Maximum 10 per webhook.
      title: InboxIds
    type__ErrorFix:
      type: string
      description: The concrete next action that resolves the error.
      title: ErrorFix
    type__Count:
      type: integer
      description: Number of items returned.
      title: Count
    type_webhooks_WebhookId:
      type: string
      description: ID of webhook.
      title: WebhookId
    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__ErrorName:
      type: string
      description: Name of error.
      title: ErrorName
    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_ClientId:
      type: string
      description: Client ID of webhook.
      title: ClientId
    type__ErrorMessage:
      type: string
      description: Error message.
      title: ErrorMessage
    type__PageToken:
      type: string
      description: Page token for pagination.
      title: PageToken
    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__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__Limit:
      type: integer
      description: Limit of number of items returned.
      title: Limit
    type_events_PodIds:
      type: array
      items:
        type: string
      description: Pods for which to send events. Maximum 10 per webhook.
      title: PodIds
    type_webhooks_Url:
      type: string
      description: URL of webhook endpoint.
      title: Url
    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_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_pods_PodId:
      type: string
      description: ID of pod.
      title: PodId
    type__Ascending:
      type: boolean
      description: Sort in ascending temporal order.
      title: Ascending
    type__ErrorDocs:
      type: string
      description: Link to the error reference entry for this code.
      title: ErrorDocs
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer