Webhooks

Fresh 🌱

AgentMail REST API reference for Webhooks. Base URL https://api.agentmail.to/v0. Authenticate with Authorization: Bearer <API_KEY>.

Create Webhook

POST https://api.agentmail.to/v0/webhooks Content-Type: application/json

CLI:

bash

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

OpenAPI Specification

yaml

openapi: 3.1.0
info:
  title: api
  version: 1.0.0
paths:
  /v0/webhooks:
    post:
      operationId: create
      summary: Create Webhook
      description: >-
        **CLI:**

        ```bash

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

        ```
      tags:
        - subpackage_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'
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
components:
  schemas:
    type_webhooks:Url:
      type: string
      description: URL of webhook endpoint.
      title: Url
    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_events:EventTypes:
      type: array
      items:
        $ref: '#/components/schemas/type_events:EventType'
      description: Event types for which to send events.
      title: EventTypes
    type_events:PodIds:
      type: array
      items:
        type: string
      description: Pods for which to send events. Maximum 10 per webhook.
      title: PodIds
    type_events:InboxIds:
      type: array
      items:
        type: string
      description: Inboxes for which to send events. Maximum 10 per webhook.
      title: InboxIds
    type_webhooks:ClientId:
      type: string
      description: Client ID of webhook.
      title: ClientId
    type_webhooks:CreateWebhookRequest:
      type: object
      properties:
        url:
          $ref: '#/components/schemas/type_webhooks:Url'
        event_types:
          $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.
        pod_ids:
          $ref: '#/components/schemas/type_events:PodIds'
        inbox_ids:
          $ref: '#/components/schemas/type_events:InboxIds'
        client_id:
          $ref: '#/components/schemas/type_webhooks:ClientId'
      required:
        - url
        - event_types
      title: CreateWebhookRequest
    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_:ErrorName:
      type: string
      description: Name of error.
      title: ErrorName
    type_:ValidationErrorResponse:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/type_:ErrorName'
        errors:
          description: Validation errors.
      required:
        - name
        - errors
      title: ValidationErrorResponse
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer

Examples

Request

json

{
  "url": "url",
  "event_types": [
    "message.received",
    "message.received"
  ]
}

Response

json

{
  "webhook_id": "webhook_id",
  "url": "url",
  "secret": "secret",
  "enabled": true,
  "updated_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "event_types": [
    "message.received",
    "message.received"
  ],
  "pod_ids": [
    "pod_ids",
    "pod_ids"
  ],
  "inbox_ids": [
    "inbox_ids",
    "inbox_ids"
  ],
  "client_id": "client_id"
}

SDK Code

typescript

import { AgentMailClient } from "agentmail";

async function main() {
    const client = new AgentMailClient({
        apiKey: "YOUR_TOKEN_HERE",
    });
    await client.webhooks.create({
        url: "url",
        eventTypes: [
            "message.received",
            "message.received",
        ],
    });
}
main();

python

from agentmail import AgentMail

client = AgentMail(
    api_key="YOUR_TOKEN_HERE",
)

client.webhooks.create(
    url="url",
    event_types=[
        "message.received",
        "message.received"
    ],
)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.agentmail.to/v0/webhooks"

	payload := strings.NewReader("{\n  \"url\": \"url\",\n  \"event_types\": [\n    \"message.received\",\n    \"message.received\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <api_key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

ruby

require 'uri'
require 'net/http'

url = URI("https://api.agentmail.to/v0/webhooks")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <api_key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"url\": \"url\",\n  \"event_types\": [\n    \"message.received\",\n    \"message.received\"\n  ]\n}"

response = http.request(request)
puts response.read_body

java

import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.agentmail.to/v0/webhooks")
  .header("Authorization", "Bearer <api_key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"url\": \"url\",\n  \"event_types\": [\n    \"message.received\",\n    \"message.received\"\n  ]\n}")
  .asString();

php

<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.agentmail.to/v0/webhooks', [
  'body' => '{
  "url": "url",
  "event_types": [
    "message.received",
    "message.received"
  ]
}',
  'headers' => [
    'Authorization' => 'Bearer <api_key>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();

csharp

using RestSharp;

var client = new RestClient("https://api.agentmail.to/v0/webhooks");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <api_key>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"url\": \"url\",\n  \"event_types\": [\n    \"message.received\",\n    \"message.received\"\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

swift

import Foundation

let headers = [
  "Authorization": "Bearer <api_key>",
  "Content-Type": "application/json"
]
let parameters = [
  "url": "url",
  "event_types": ["message.received", "message.received"]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.agentmail.to/v0/webhooks")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()

Get Webhook

GET https://api.agentmail.to/v0/webhooks/{webhook_id}

CLI:

bash

agentmail webhooks get --webhook-id <webhook_id>

OpenAPI Specification

yaml

openapi: 3.1.0
info:
  title: api
  version: 1.0.0
paths:
  /v0/webhooks/{webhook_id}:
    get:
      operationId: get
      summary: Get Webhook
      description: |-
        **CLI:**
        ```bash
        agentmail webhooks get --webhook-id <webhook_id>
        ```
      tags:
        - subpackage_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'
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
components:
  schemas:
    type_webhooks:WebhookId:
      type: string
      description: ID of webhook.
      title: WebhookId
    type_webhooks:Url:
      type: string
      description: URL of webhook endpoint.
      title: Url
    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_events:EventTypes:
      type: array
      items:
        $ref: '#/components/schemas/type_events:EventType'
      description: Event types for which to send events.
      title: EventTypes
    type_events:PodIds:
      type: array
      items:
        type: string
      description: Pods for which to send events. Maximum 10 per webhook.
      title: PodIds
    type_events:InboxIds:
      type: array
      items:
        type: string
      description: Inboxes for which to send events. Maximum 10 per webhook.
      title: InboxIds
    type_webhooks:ClientId:
      type: string
      description: Client ID of webhook.
      title: ClientId
    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_:ErrorName:
      type: string
      description: Name of error.
      title: ErrorName
    type_:ErrorMessage:
      type: string
      description: Error message.
      title: ErrorMessage
    type_:ErrorResponse:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/type_:ErrorName'
        message:
          $ref: '#/components/schemas/type_:ErrorMessage'
      required:
        - name
        - message
      title: ErrorResponse
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer

Examples

Response

json

{
  "webhook_id": "webhook_id",
  "url": "url",
  "secret": "secret",
  "enabled": true,
  "updated_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "event_types": [
    "message.received",
    "message.received"
  ],
  "pod_ids": [
    "pod_ids",
    "pod_ids"
  ],
  "inbox_ids": [
    "inbox_ids",
    "inbox_ids"
  ],
  "client_id": "client_id"
}

SDK Code

typescript

import { AgentMailClient } from "agentmail";

async function main() {
    const client = new AgentMailClient({
        apiKey: "YOUR_TOKEN_HERE",
    });
    await client.webhooks.get("webhook_id");
}
main();

python

from agentmail import AgentMail

client = AgentMail(
    api_key="YOUR_TOKEN_HERE",
)

client.webhooks.get(
    webhook_id="webhook_id",
)

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.agentmail.to/v0/webhooks/webhook_id"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <api_key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

ruby

require 'uri'
require 'net/http'

url = URI("https://api.agentmail.to/v0/webhooks/webhook_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <api_key>'

response = http.request(request)
puts response.read_body

java

import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.agentmail.to/v0/webhooks/webhook_id")
  .header("Authorization", "Bearer <api_key>")
  .asString();

php

<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.agentmail.to/v0/webhooks/webhook_id', [
  'headers' => [
    'Authorization' => 'Bearer <api_key>',
  ],
]);

echo $response->getBody();

csharp

using RestSharp;

var client = new RestClient("https://api.agentmail.to/v0/webhooks/webhook_id");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <api_key>");
IRestResponse response = client.Execute(request);

swift

import Foundation

let headers = ["Authorization": "Bearer <api_key>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.agentmail.to/v0/webhooks/webhook_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()

List Webhooks

GET https://api.agentmail.to/v0/webhooks

CLI:

bash

agentmail webhooks list

OpenAPI Specification

yaml

openapi: 3.1.0
info:
  title: api
  version: 1.0.0
paths:
  /v0/webhooks:
    get:
      operationId: list
      summary: List Webhooks
      description: |-
        **CLI:**
        ```bash
        agentmail webhooks list
        ```
      tags:
        - subpackage_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'
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
components:
  schemas:
    type_:Limit:
      type: integer
      description: Limit of number of items returned.
      title: Limit
    type_:PageToken:
      type: string
      description: Page token for pagination.
      title: PageToken
    type_:Ascending:
      type: boolean
      description: Sort in ascending temporal order.
      title: Ascending
    type_:Count:
      type: integer
      description: Number of items returned.
      title: Count
    type_webhooks:WebhookId:
      type: string
      description: ID of webhook.
      title: WebhookId
    type_webhooks:Url:
      type: string
      description: URL of webhook endpoint.
      title: Url
    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_events:EventTypes:
      type: array
      items:
        $ref: '#/components/schemas/type_events:EventType'
      description: Event types for which to send events.
      title: EventTypes
    type_events:PodIds:
      type: array
      items:
        type: string
      description: Pods for which to send events. Maximum 10 per webhook.
      title: PodIds
    type_events:InboxIds:
      type: array
      items:
        type: string
      description: Inboxes for which to send events. Maximum 10 per webhook.
      title: InboxIds
    type_webhooks:ClientId:
      type: string
      description: Client ID of webhook.
      title: ClientId
    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: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
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer

Examples

Response

json

{
  "count": 1,
  "webhooks": [
    {
      "webhook_id": "webhook_id",
      "url": "url",
      "secret": "secret",
      "enabled": true,
      "updated_at": "2024-01-15T09:30:00Z",
      "created_at": "2024-01-15T09:30:00Z",
      "event_types": [
        "message.received",
        "message.received"
      ],
      "pod_ids": [
        "pod_ids",
        "pod_ids"
      ],
      "inbox_ids": [
        "inbox_ids",
        "inbox_ids"
      ],
      "client_id": "client_id"
    },
    {
      "webhook_id": "webhook_id",
      "url": "url",
      "secret": "secret",
      "enabled": true,
      "updated_at": "2024-01-15T09:30:00Z",
      "created_at": "2024-01-15T09:30:00Z",
      "event_types": [
        "message.received",
        "message.received"
      ],
      "pod_ids": [
        "pod_ids",
        "pod_ids"
      ],
      "inbox_ids": [
        "inbox_ids",
        "inbox_ids"
      ],
      "client_id": "client_id"
    }
  ],
  "limit": 1,
  "next_page_token": "next_page_token"
}

SDK Code

typescript

import { AgentMailClient } from "agentmail";

async function main() {
    const client = new AgentMailClient({
        apiKey: "YOUR_TOKEN_HERE",
    });
    await client.webhooks.list({});
}
main();

python

from agentmail import AgentMail

client = AgentMail(
    api_key="YOUR_TOKEN_HERE",
)

client.webhooks.list()

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.agentmail.to/v0/webhooks"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <api_key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

ruby

require 'uri'
require 'net/http'

url = URI("https://api.agentmail.to/v0/webhooks")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <api_key>'

response = http.request(request)
puts response.read_body

java

import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.agentmail.to/v0/webhooks")
  .header("Authorization", "Bearer <api_key>")
  .asString();

php

<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.agentmail.to/v0/webhooks', [
  'headers' => [
    'Authorization' => 'Bearer <api_key>',
  ],
]);

echo $response->getBody();

csharp

using RestSharp;

var client = new RestClient("https://api.agentmail.to/v0/webhooks");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <api_key>");
IRestResponse response = client.Execute(request);

swift

import Foundation

let headers = ["Authorization": "Bearer <api_key>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.agentmail.to/v0/webhooks")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()

Update Webhook

PATCH https://api.agentmail.to/v0/webhooks/{webhook_id} Content-Type: application/json

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>

OpenAPI Specification

yaml

openapi: 3.1.0
info:
  title: api
  version: 1.0.0
paths:
  /v0/webhooks/{webhook_id}:
    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:
        - subpackage_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'
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
components:
  schemas:
    type_webhooks:WebhookId:
      type: string
      description: ID of webhook.
      title: WebhookId
    type_events:InboxIds:
      type: array
      items:
        type: string
      description: Inboxes for which to send events. Maximum 10 per webhook.
      title: InboxIds
    type_events:PodIds:
      type: array
      items:
        type: string
      description: Pods for which to send events. Maximum 10 per webhook.
      title: PodIds
    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_events:EventTypes:
      type: array
      items:
        $ref: '#/components/schemas/type_events:EventType'
      description: Event types for which to send events.
      title: EventTypes
    type_webhooks:UpdateWebhookRequest:
      type: object
      properties:
        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.
        event_types:
          $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: UpdateWebhookRequest
    type_webhooks:Url:
      type: string
      description: URL of webhook endpoint.
      title: Url
    type_webhooks:ClientId:
      type: string
      description: Client ID of webhook.
      title: ClientId
    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_:ErrorName:
      type: string
      description: Name of error.
      title: ErrorName
    type_:ErrorMessage:
      type: string
      description: Error message.
      title: ErrorMessage
    type_:ErrorResponse:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/type_:ErrorName'
        message:
          $ref: '#/components/schemas/type_:ErrorMessage'
      required:
        - name
        - message
      title: ErrorResponse
    type_:ValidationErrorResponse:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/type_:ErrorName'
        errors:
          description: Validation errors.
      required:
        - name
        - errors
      title: ValidationErrorResponse
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer

Examples

Request

json

{}

Response

json

{
  "webhook_id": "webhook_id",
  "url": "url",
  "secret": "secret",
  "enabled": true,
  "updated_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "event_types": [
    "message.received",
    "message.received"
  ],
  "pod_ids": [
    "pod_ids",
    "pod_ids"
  ],
  "inbox_ids": [
    "inbox_ids",
    "inbox_ids"
  ],
  "client_id": "client_id"
}

SDK Code

typescript

import { AgentMailClient } from "agentmail";

async function main() {
    const client = new AgentMailClient({
        apiKey: "YOUR_TOKEN_HERE",
    });
    await client.webhooks.update("webhook_id", {});
}
main();

python

from agentmail import AgentMail

client = AgentMail(
    api_key="YOUR_TOKEN_HERE",
)

client.webhooks.update(
    webhook_id="webhook_id",
)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.agentmail.to/v0/webhooks/webhook_id"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <api_key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

ruby

require 'uri'
require 'net/http'

url = URI("https://api.agentmail.to/v0/webhooks/webhook_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <api_key>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body

java

import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.patch("https://api.agentmail.to/v0/webhooks/webhook_id")
  .header("Authorization", "Bearer <api_key>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();

php

<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.agentmail.to/v0/webhooks/webhook_id', [
  'body' => '{}',
  'headers' => [
    'Authorization' => 'Bearer <api_key>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();

csharp

using RestSharp;

var client = new RestClient("https://api.agentmail.to/v0/webhooks/webhook_id");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Authorization", "Bearer <api_key>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

swift

import Foundation

let headers = [
  "Authorization": "Bearer <api_key>",
  "Content-Type": "application/json"
]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.agentmail.to/v0/webhooks/webhook_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()

Delete Webhook

DELETE https://api.agentmail.to/v0/webhooks/{webhook_id}

CLI:

bash

agentmail webhooks delete --webhook-id <webhook_id>

OpenAPI Specification

yaml

openapi: 3.1.0
info:
  title: api
  version: 1.0.0
paths:
  /v0/webhooks/{webhook_id}:
    delete:
      operationId: delete
      summary: Delete Webhook
      description: |-
        **CLI:**
        ```bash
        agentmail webhooks delete --webhook-id <webhook_id>
        ```
      tags:
        - subpackage_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'
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
components:
  schemas:
    type_webhooks:WebhookId:
      type: string
      description: ID of webhook.
      title: WebhookId
    type_:ErrorName:
      type: string
      description: Name of error.
      title: ErrorName
    type_:ErrorMessage:
      type: string
      description: Error message.
      title: ErrorMessage
    type_:ErrorResponse:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/type_:ErrorName'
        message:
          $ref: '#/components/schemas/type_:ErrorMessage'
      required:
        - name
        - message
      title: ErrorResponse
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer

Examples

SDK Code

typescript

import { AgentMailClient } from "agentmail";

async function main() {
    const client = new AgentMailClient({
        apiKey: "YOUR_TOKEN_HERE",
    });
    await client.webhooks.delete("webhook_id");
}
main();

python

from agentmail import AgentMail

client = AgentMail(
    api_key="YOUR_TOKEN_HERE",
)

client.webhooks.delete(
    webhook_id="webhook_id",
)

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.agentmail.to/v0/webhooks/webhook_id"

	req, _ := http.NewRequest("DELETE", url, nil)

	req.Header.Add("Authorization", "Bearer <api_key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

ruby

require 'uri'
require 'net/http'

url = URI("https://api.agentmail.to/v0/webhooks/webhook_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)
request["Authorization"] = 'Bearer <api_key>'

response = http.request(request)
puts response.read_body

java

import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.delete("https://api.agentmail.to/v0/webhooks/webhook_id")
  .header("Authorization", "Bearer <api_key>")
  .asString();

php

<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('DELETE', 'https://api.agentmail.to/v0/webhooks/webhook_id', [
  'headers' => [
    'Authorization' => 'Bearer <api_key>',
  ],
]);

echo $response->getBody();

csharp

using RestSharp;

var client = new RestClient("https://api.agentmail.to/v0/webhooks/webhook_id");
var request = new RestRequest(Method.DELETE);
request.AddHeader("Authorization", "Bearer <api_key>");
IRestResponse response = client.Execute(request);

swift

import Foundation

let headers = ["Authorization": "Bearer <api_key>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.agentmail.to/v0/webhooks/webhook_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "DELETE"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()

Event: message.received

POST

OpenAPI 3.1 Webhook Specification

yaml

openapi: 3.1.0
info:
  title: api
  version: 1.0.0
paths: {}
webhooks:
  message-received:
    post:
      operationId: message-received
      summary: Message Received
      parameters:
        - name: svix-id
          in: header
          required: true
          schema:
            $ref: '#/components/schemas/type_webhooks/events:SvixId'
        - name: svix-signature
          in: header
          required: true
          schema:
            $ref: '#/components/schemas/type_webhooks/events:SvixSignature'
        - name: svix-timestamp
          in: header
          required: true
          schema:
            $ref: '#/components/schemas/type_webhooks/events:SvixTimestamp'
      responses:
        '200':
          description: Webhook received successfully
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_events:MessageReceivedEvent'
components:
  schemas:
    type_webhooks/events:SvixId:
      type: string
      description: ID of webhook message.
      title: SvixId
    type_webhooks/events:SvixSignature:
      type: string
      description: Signature of webhook message.
      title: SvixSignature
    type_webhooks/events:SvixTimestamp:
      type: string
      format: date-time
      description: Timestamp of webhook message.
      title: SvixTimestamp
    type_events:MessageReceivedEventType:
      type: string
      enum:
        - message.received
        - message.received.spam
        - message.received.blocked
        - message.received.unauthenticated
      title: MessageReceivedEventType
    type_events:EventId:
      type: string
      description: ID of event.
      title: EventId
    type_inboxes:InboxId:
      type: string
      description: The ID of the inbox.
      title: InboxId
    type_threads:ThreadId:
      type: string
      description: ID of thread.
      title: ThreadId
    type_messages:MessageId:
      type: string
      description: ID of message.
      title: MessageId
    type_messages:MessageLabels:
      type: array
      items:
        type: string
      description: Labels of message.
      title: MessageLabels
    type_messages:MessageTimestamp:
      type: string
      format: date-time
      description: Time at which message was sent or drafted.
      title: MessageTimestamp
    type_messages:MessageFrom:
      type: string
      description: >-
        Address of sender. In format `username@domain.com` or `Display Name
        <username@domain.com>`.
      title: MessageFrom
    type_messages:MessageTo:
      type: array
      items:
        type: string
      description: >-
        Addresses of recipients. In format `username@domain.com` or `Display
        Name <username@domain.com>`.
      title: MessageTo
    type_messages:MessageCc:
      type: array
      items:
        type: string
      description: >-
        Addresses of CC recipients. In format `username@domain.com` or `Display
        Name <username@domain.com>`.
      title: MessageCc
    type_messages:MessageBcc:
      type: array
      items:
        type: string
      description: >-
        Addresses of BCC recipients. In format `username@domain.com` or `Display
        Name <username@domain.com>`.
      title: MessageBcc
    type_messages:MessageSubject:
      type: string
      description: Subject of message.
      title: MessageSubject
    type_messages:MessagePreview:
      type: string
      description: Text preview of message.
      title: MessagePreview
    type_messages:MessageText:
      type: string
      description: Plain text body of message.
      title: MessageText
    type_messages:MessageHtml:
      type: string
      description: HTML body of message.
      title: MessageHtml
    type_attachments:AttachmentId:
      type: string
      description: ID of attachment.
      title: AttachmentId
    type_attachments:AttachmentFilename:
      type: string
      description: Filename of attachment.
      title: AttachmentFilename
    type_attachments:AttachmentSize:
      type: integer
      description: Size of attachment in bytes.
      title: AttachmentSize
    type_attachments:AttachmentContentType:
      type: string
      description: Content type of attachment.
      title: AttachmentContentType
    type_attachments:AttachmentContentDisposition:
      type: string
      enum:
        - inline
        - attachment
      description: Content disposition of attachment.
      title: AttachmentContentDisposition
    type_attachments:AttachmentContentId:
      type: string
      description: Content ID of attachment.
      title: AttachmentContentId
    type_attachments:Attachment:
      type: object
      properties:
        attachment_id:
          $ref: '#/components/schemas/type_attachments:AttachmentId'
        filename:
          $ref: '#/components/schemas/type_attachments:AttachmentFilename'
        size:
          $ref: '#/components/schemas/type_attachments:AttachmentSize'
        content_type:
          $ref: '#/components/schemas/type_attachments:AttachmentContentType'
        content_disposition:
          $ref: '#/components/schemas/type_attachments:AttachmentContentDisposition'
        content_id:
          $ref: '#/components/schemas/type_attachments:AttachmentContentId'
      required:
        - attachment_id
        - size
      title: Attachment
    type_messages:MessageAttachments:
      type: array
      items:
        $ref: '#/components/schemas/type_attachments:Attachment'
      description: Attachments in message.
      title: MessageAttachments
    type_messages:MessageInReplyTo:
      type: string
      description: ID of message being replied to.
      title: MessageInReplyTo
    type_messages:MessageReferences:
      type: array
      items:
        type: string
      description: IDs of previous messages in thread.
      title: MessageReferences
    type_messages:MessageHeaders:
      type: object
      additionalProperties:
        type: string
      description: Headers in message.
      title: MessageHeaders
    type_messages:MessageSize:
      type: integer
      description: Size of message in bytes.
      title: MessageSize
    type_messages:MessageUpdatedAt:
      type: string
      format: date-time
      description: Time at which message was last updated.
      title: MessageUpdatedAt
    type_messages:MessageCreatedAt:
      type: string
      format: date-time
      description: Time at which message was created.
      title: MessageCreatedAt
    type_messages:Message:
      type: object
      properties:
        inbox_id:
          $ref: '#/components/schemas/type_inboxes:InboxId'
        thread_id:
          $ref: '#/components/schemas/type_threads:ThreadId'
        message_id:
          $ref: '#/components/schemas/type_messages:MessageId'
        labels:
          $ref: '#/components/schemas/type_messages:MessageLabels'
        timestamp:
          $ref: '#/components/schemas/type_messages:MessageTimestamp'
        from:
          $ref: '#/components/schemas/type_messages:MessageFrom'
        reply_to:
          type: array
          items:
            type: string
          description: >-
            Reply-to addresses. In format `username@domain.com` or `Display Name
            <username@domain.com>`.
        to:
          $ref: '#/components/schemas/type_messages:MessageTo'
        cc:
          $ref: '#/components/schemas/type_messages:MessageCc'
        bcc:
          $ref: '#/components/schemas/type_messages:MessageBcc'
        subject:
          $ref: '#/components/schemas/type_messages:MessageSubject'
        preview:
          $ref: '#/components/schemas/type_messages:MessagePreview'
        text:
          $ref: '#/components/schemas/type_messages:MessageText'
        html:
          $ref: '#/components/schemas/type_messages:MessageHtml'
        extracted_text:
          type: string
          description: Extracted new text content.
        extracted_html:
          type: string
          description: Extracted new HTML content.
        attachments:
          $ref: '#/components/schemas/type_messages:MessageAttachments'
        in_reply_to:
          $ref: '#/components/schemas/type_messages:MessageInReplyTo'
        references:
          $ref: '#/components/schemas/type_messages:MessageReferences'
        headers:
          $ref: '#/components/schemas/type_messages:MessageHeaders'
        size:
          $ref: '#/components/schemas/type_messages:MessageSize'
        updated_at:
          $ref: '#/components/schemas/type_messages:MessageUpdatedAt'
        created_at:
          $ref: '#/components/schemas/type_messages:MessageCreatedAt'
      required:
        - inbox_id
        - thread_id
        - message_id
        - labels
        - timestamp
        - from
        - to
        - size
        - updated_at
        - created_at
      title: Message
    type_threads:ThreadLabels:
      type: array
      items:
        type: string
      description: Labels of thread.
      title: ThreadLabels
    type_threads:ThreadTimestamp:
      type: string
      format: date-time
      description: Timestamp of last sent or received message.
      title: ThreadTimestamp
    type_threads:ThreadReceivedTimestamp:
      type: string
      format: date-time
      description: Timestamp of last received message.
      title: ThreadReceivedTimestamp
    type_threads:ThreadSentTimestamp:
      type: string
      format: date-time
      description: Timestamp of last sent message.
      title: ThreadSentTimestamp
    type_threads:ThreadSenders:
      type: array
      items:
        type: string
      description: >-
        Senders in thread. In format `username@domain.com` or `Display Name
        <username@domain.com>`.
      title: ThreadSenders
    type_threads:ThreadRecipients:
      type: array
      items:
        type: string
      description: >-
        Recipients in thread. In format `username@domain.com` or `Display Name
        <username@domain.com>`.
      title: ThreadRecipients
    type_threads:ThreadSubject:
      type: string
      description: Subject of thread.
      title: ThreadSubject
    type_threads:ThreadPreview:
      type: string
      description: Text preview of last message in thread.
      title: ThreadPreview
    type_threads:ThreadAttachments:
      type: array
      items:
        $ref: '#/components/schemas/type_attachments:Attachment'
      description: Attachments in thread.
      title: ThreadAttachments
    type_threads:ThreadLastMessageId:
      type: string
      description: ID of last message in thread.
      title: ThreadLastMessageId
    type_threads:ThreadMessageCount:
      type: integer
      description: Number of messages in thread.
      title: ThreadMessageCount
    type_threads:ThreadSize:
      type: integer
      description: Size of thread in bytes.
      title: ThreadSize
    type_threads:ThreadUpdatedAt:
      type: string
      format: date-time
      description: Time at which thread was last updated.
      title: ThreadUpdatedAt
    type_threads:ThreadCreatedAt:
      type: string
      format: date-time
      description: Time at which thread was created.
      title: ThreadCreatedAt
    type_threads:ThreadItem:
      type: object
      properties:
        inbox_id:
          $ref: '#/components/schemas/type_inboxes:InboxId'
        thread_id:
          $ref: '#/components/schemas/type_threads:ThreadId'
        labels:
          $ref: '#/components/schemas/type_threads:ThreadLabels'
        timestamp:
          $ref: '#/components/schemas/type_threads:ThreadTimestamp'
        received_timestamp:
          $ref: '#/components/schemas/type_threads:ThreadReceivedTimestamp'
        sent_timestamp:
          $ref: '#/components/schemas/type_threads:ThreadSentTimestamp'
        senders:
          $ref: '#/components/schemas/type_threads:ThreadSenders'
        recipients:
          $ref: '#/components/schemas/type_threads:ThreadRecipients'
        subject:
          $ref: '#/components/schemas/type_threads:ThreadSubject'
        preview:
          $ref: '#/components/schemas/type_threads:ThreadPreview'
        attachments:
          $ref: '#/components/schemas/type_threads:ThreadAttachments'
        last_message_id:
          $ref: '#/components/schemas/type_threads:ThreadLastMessageId'
        message_count:
          $ref: '#/components/schemas/type_threads:ThreadMessageCount'
        size:
          $ref: '#/components/schemas/type_threads:ThreadSize'
        updated_at:
          $ref: '#/components/schemas/type_threads:ThreadUpdatedAt'
        created_at:
          $ref: '#/components/schemas/type_threads:ThreadCreatedAt'
      required:
        - inbox_id
        - thread_id
        - labels
        - timestamp
        - senders
        - recipients
        - last_message_id
        - message_count
        - size
        - updated_at
        - created_at
      title: ThreadItem
    type_events:MessageReceivedEvent:
      type: object
      properties:
        type:
          type: string
          enum:
            - event
        event_type:
          $ref: '#/components/schemas/type_events:MessageReceivedEventType'
        event_id:
          $ref: '#/components/schemas/type_events:EventId'
        message:
          $ref: '#/components/schemas/type_messages:Message'
        thread:
          $ref: '#/components/schemas/type_threads:ThreadItem'
      required:
        - type
        - event_type
        - event_id
        - message
        - thread
      description: >-
        A message was received. Spam, blocked, and unauthenticated
        received-message events use the same payload shape with different
        `event_type` values.
      title: MessageReceivedEvent

Event: message.sent

POST

OpenAPI 3.1 Webhook Specification

yaml

openapi: 3.1.0
info:
  title: api
  version: 1.0.0
paths: {}
webhooks:
  message-sent:
    post:
      operationId: message-sent
      summary: Message Sent
      parameters:
        - name: svix-id
          in: header
          required: true
          schema:
            $ref: '#/components/schemas/type_webhooks/events:SvixId'
        - name: svix-signature
          in: header
          required: true
          schema:
            $ref: '#/components/schemas/type_webhooks/events:SvixSignature'
        - name: svix-timestamp
          in: header
          required: true
          schema:
            $ref: '#/components/schemas/type_webhooks/events:SvixTimestamp'
      responses:
        '200':
          description: Webhook received successfully
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_events:MessageSentEvent'
components:
  schemas:
    type_webhooks/events:SvixId:
      type: string
      description: ID of webhook message.
      title: SvixId
    type_webhooks/events:SvixSignature:
      type: string
      description: Signature of webhook message.
      title: SvixSignature
    type_webhooks/events:SvixTimestamp:
      type: string
      format: date-time
      description: Timestamp of webhook message.
      title: SvixTimestamp
    type_events:EventId:
      type: string
      description: ID of event.
      title: EventId
    type_inboxes:InboxId:
      type: string
      description: The ID of the inbox.
      title: InboxId
    type_threads:ThreadId:
      type: string
      description: ID of thread.
      title: ThreadId
    type_messages:MessageId:
      type: string
      description: ID of message.
      title: MessageId
    type_events:Timestamp:
      type: string
      format: date-time
      description: Timestamp of event.
      title: Timestamp
    type_events:Send:
      type: object
      properties:
        inbox_id:
          $ref: '#/components/schemas/type_inboxes:InboxId'
        thread_id:
          $ref: '#/components/schemas/type_threads:ThreadId'
        message_id:
          $ref: '#/components/schemas/type_messages:MessageId'
        timestamp:
          $ref: '#/components/schemas/type_events:Timestamp'
        recipients:
          type: array
          items:
            type: string
          description: Sent recipients.
      required:
        - inbox_id
        - thread_id
        - message_id
        - timestamp
        - recipients
      title: Send
    type_events:MessageSentEvent:
      type: object
      properties:
        type:
          type: string
          enum:
            - event
        event_type:
          type: string
          enum:
            - message.sent
        event_id:
          $ref: '#/components/schemas/type_events:EventId'
        send:
          $ref: '#/components/schemas/type_events:Send'
      required:
        - type
        - event_type
        - event_id
        - send
      title: MessageSentEvent

Event: message.delivered

POST

OpenAPI 3.1 Webhook Specification

yaml

openapi: 3.1.0
info:
  title: api
  version: 1.0.0
paths: {}
webhooks:
  message-delivered:
    post:
      operationId: message-delivered
      summary: Message Delivered
      parameters:
        - name: svix-id
          in: header
          required: true
          schema:
            $ref: '#/components/schemas/type_webhooks/events:SvixId'
        - name: svix-signature
          in: header
          required: true
          schema:
            $ref: '#/components/schemas/type_webhooks/events:SvixSignature'
        - name: svix-timestamp
          in: header
          required: true
          schema:
            $ref: '#/components/schemas/type_webhooks/events:SvixTimestamp'
      responses:
        '200':
          description: Webhook received successfully
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_events:MessageDeliveredEvent'
components:
  schemas:
    type_webhooks/events:SvixId:
      type: string
      description: ID of webhook message.
      title: SvixId
    type_webhooks/events:SvixSignature:
      type: string
      description: Signature of webhook message.
      title: SvixSignature
    type_webhooks/events:SvixTimestamp:
      type: string
      format: date-time
      description: Timestamp of webhook message.
      title: SvixTimestamp
    type_events:EventId:
      type: string
      description: ID of event.
      title: EventId
    type_inboxes:InboxId:
      type: string
      description: The ID of the inbox.
      title: InboxId
    type_threads:ThreadId:
      type: string
      description: ID of thread.
      title: ThreadId
    type_messages:MessageId:
      type: string
      description: ID of message.
      title: MessageId
    type_events:Timestamp:
      type: string
      format: date-time
      description: Timestamp of event.
      title: Timestamp
    type_events:Delivery:
      type: object
      properties:
        inbox_id:
          $ref: '#/components/schemas/type_inboxes:InboxId'
        thread_id:
          $ref: '#/components/schemas/type_threads:ThreadId'
        message_id:
          $ref: '#/components/schemas/type_messages:MessageId'
        timestamp:
          $ref: '#/components/schemas/type_events:Timestamp'
        recipients:
          type: array
          items:
            type: string
          description: Delivered recipients.
      required:
        - inbox_id
        - thread_id
        - message_id
        - timestamp
        - recipients
      title: Delivery
    type_events:MessageDeliveredEvent:
      type: object
      properties:
        type:
          type: string
          enum:
            - event
        event_type:
          type: string
          enum:
            - message.delivered
        event_id:
          $ref: '#/components/schemas/type_events:EventId'
        delivery:
          $ref: '#/components/schemas/type_events:Delivery'
      required:
        - type
        - event_type
        - event_id
        - delivery
      title: MessageDeliveredEvent

Event: message.bounced

POST

OpenAPI 3.1 Webhook Specification

yaml

openapi: 3.1.0
info:
  title: api
  version: 1.0.0
paths: {}
webhooks:
  message-bounced:
    post:
      operationId: message-bounced
      summary: Message Bounced
      parameters:
        - name: svix-id
          in: header
          required: true
          schema:
            $ref: '#/components/schemas/type_webhooks/events:SvixId'
        - name: svix-signature
          in: header
          required: true
          schema:
            $ref: '#/components/schemas/type_webhooks/events:SvixSignature'
        - name: svix-timestamp
          in: header
          required: true
          schema:
            $ref: '#/components/schemas/type_webhooks/events:SvixTimestamp'
      responses:
        '200':
          description: Webhook received successfully
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_events:MessageBouncedEvent'
components:
  schemas:
    type_webhooks/events:SvixId:
      type: string
      description: ID of webhook message.
      title: SvixId
    type_webhooks/events:SvixSignature:
      type: string
      description: Signature of webhook message.
      title: SvixSignature
    type_webhooks/events:SvixTimestamp:
      type: string
      format: date-time
      description: Timestamp of webhook message.
      title: SvixTimestamp
    type_events:EventId:
      type: string
      description: ID of event.
      title: EventId
    type_inboxes:InboxId:
      type: string
      description: The ID of the inbox.
      title: InboxId
    type_threads:ThreadId:
      type: string
      description: ID of thread.
      title: ThreadId
    type_messages:MessageId:
      type: string
      description: ID of message.
      title: MessageId
    type_events:Timestamp:
      type: string
      format: date-time
      description: Timestamp of event.
      title: Timestamp
    type_events:Recipient:
      type: object
      properties:
        address:
          type: string
          description: Recipient address.
        status:
          type: string
          description: Recipient status.
      required:
        - address
        - status
      title: Recipient
    type_events:Bounce:
      type: object
      properties:
        inbox_id:
          $ref: '#/components/schemas/type_inboxes:InboxId'
        thread_id:
          $ref: '#/components/schemas/type_threads:ThreadId'
        message_id:
          $ref: '#/components/schemas/type_messages:MessageId'
        timestamp:
          $ref: '#/components/schemas/type_events:Timestamp'
        type:
          type: string
          description: Bounce type.
        sub_type:
          type: string
          description: Bounce sub-type.
        recipients:
          type: array
          items:
            $ref: '#/components/schemas/type_events:Recipient'
          description: Bounced recipients.
      required:
        - inbox_id
        - thread_id
        - message_id
        - timestamp
        - type
        - sub_type
        - recipients
      title: Bounce
    type_events:MessageBouncedEvent:
      type: object
      properties:
        type:
          type: string
          enum:
            - event
        event_type:
          type: string
          enum:
            - message.bounced
        event_id:
          $ref: '#/components/schemas/type_events:EventId'
        bounce:
          $ref: '#/components/schemas/type_events:Bounce'
      required:
        - type
        - event_type
        - event_id
        - bounce
      title: MessageBouncedEvent

Event: message.rejected

POST

OpenAPI 3.1 Webhook Specification

yaml

openapi: 3.1.0
info:
  title: api
  version: 1.0.0
paths: {}
webhooks:
  message-rejected:
    post:
      operationId: message-rejected
      summary: Message Rejected
      parameters:
        - name: svix-id
          in: header
          required: true
          schema:
            $ref: '#/components/schemas/type_webhooks/events:SvixId'
        - name: svix-signature
          in: header
          required: true
          schema:
            $ref: '#/components/schemas/type_webhooks/events:SvixSignature'
        - name: svix-timestamp
          in: header
          required: true
          schema:
            $ref: '#/components/schemas/type_webhooks/events:SvixTimestamp'
      responses:
        '200':
          description: Webhook received successfully
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_events:MessageRejectedEvent'
components:
  schemas:
    type_webhooks/events:SvixId:
      type: string
      description: ID of webhook message.
      title: SvixId
    type_webhooks/events:SvixSignature:
      type: string
      description: Signature of webhook message.
      title: SvixSignature
    type_webhooks/events:SvixTimestamp:
      type: string
      format: date-time
      description: Timestamp of webhook message.
      title: SvixTimestamp
    type_events:EventId:
      type: string
      description: ID of event.
      title: EventId
    type_inboxes:InboxId:
      type: string
      description: The ID of the inbox.
      title: InboxId
    type_threads:ThreadId:
      type: string
      description: ID of thread.
      title: ThreadId
    type_messages:MessageId:
      type: string
      description: ID of message.
      title: MessageId
    type_events:Timestamp:
      type: string
      format: date-time
      description: Timestamp of event.
      title: Timestamp
    type_events:Reject:
      type: object
      properties:
        inbox_id:
          $ref: '#/components/schemas/type_inboxes:InboxId'
        thread_id:
          $ref: '#/components/schemas/type_threads:ThreadId'
        message_id:
          $ref: '#/components/schemas/type_messages:MessageId'
        timestamp:
          $ref: '#/components/schemas/type_events:Timestamp'
        reason:
          type: string
          description: Reject reason.
      required:
        - inbox_id
        - thread_id
        - message_id
        - timestamp
        - reason
      title: Reject
    type_events:MessageRejectedEvent:
      type: object
      properties:
        type:
          type: string
          enum:
            - event
        event_type:
          type: string
          enum:
            - message.rejected
        event_id:
          $ref: '#/components/schemas/type_events:EventId'
        reject:
          $ref: '#/components/schemas/type_events:Reject'
      required:
        - type
        - event_type
        - event_id
        - reject
      title: MessageRejectedEvent

Event: message.complained

POST

OpenAPI 3.1 Webhook Specification

yaml

openapi: 3.1.0
info:
  title: api
  version: 1.0.0
paths: {}
webhooks:
  message-complained:
    post:
      operationId: message-complained
      summary: Message Complained
      parameters:
        - name: svix-id
          in: header
          required: true
          schema:
            $ref: '#/components/schemas/type_webhooks/events:SvixId'
        - name: svix-signature
          in: header
          required: true
          schema:
            $ref: '#/components/schemas/type_webhooks/events:SvixSignature'
        - name: svix-timestamp
          in: header
          required: true
          schema:
            $ref: '#/components/schemas/type_webhooks/events:SvixTimestamp'
      responses:
        '200':
          description: Webhook received successfully
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_events:MessageComplainedEvent'
components:
  schemas:
    type_webhooks/events:SvixId:
      type: string
      description: ID of webhook message.
      title: SvixId
    type_webhooks/events:SvixSignature:
      type: string
      description: Signature of webhook message.
      title: SvixSignature
    type_webhooks/events:SvixTimestamp:
      type: string
      format: date-time
      description: Timestamp of webhook message.
      title: SvixTimestamp
    type_events:EventId:
      type: string
      description: ID of event.
      title: EventId
    type_inboxes:InboxId:
      type: string
      description: The ID of the inbox.
      title: InboxId
    type_threads:ThreadId:
      type: string
      description: ID of thread.
      title: ThreadId
    type_messages:MessageId:
      type: string
      description: ID of message.
      title: MessageId
    type_events:Timestamp:
      type: string
      format: date-time
      description: Timestamp of event.
      title: Timestamp
    type_events:Complaint:
      type: object
      properties:
        inbox_id:
          $ref: '#/components/schemas/type_inboxes:InboxId'
        thread_id:
          $ref: '#/components/schemas/type_threads:ThreadId'
        message_id:
          $ref: '#/components/schemas/type_messages:MessageId'
        timestamp:
          $ref: '#/components/schemas/type_events:Timestamp'
        type:
          type: string
          description: Complaint type.
        sub_type:
          type: string
          description: Complaint sub-type.
        recipients:
          type: array
          items:
            type: string
          description: Complained recipients.
      required:
        - inbox_id
        - thread_id
        - message_id
        - timestamp
        - type
        - sub_type
        - recipients
      title: Complaint
    type_events:MessageComplainedEvent:
      type: object
      properties:
        type:
          type: string
          enum:
            - event
        event_type:
          type: string
          enum:
            - message.complained
        event_id:
          $ref: '#/components/schemas/type_events:EventId'
        complaint:
          $ref: '#/components/schemas/type_events:Complaint'
      required:
        - type
        - event_type
        - event_id
        - complaint
      title: MessageComplainedEvent

Event: domain.verified

POST

OpenAPI 3.1 Webhook Specification

yaml

openapi: 3.1.0
info:
  title: api
  version: 1.0.0
paths: {}
webhooks:
  domain-verified:
    post:
      operationId: domain-verified
      summary: Domain Verified
      parameters:
        - name: svix-id
          in: header
          required: true
          schema:
            $ref: '#/components/schemas/type_webhooks/events:SvixId'
        - name: svix-signature
          in: header
          required: true
          schema:
            $ref: '#/components/schemas/type_webhooks/events:SvixSignature'
        - name: svix-timestamp
          in: header
          required: true
          schema:
            $ref: '#/components/schemas/type_webhooks/events:SvixTimestamp'
      responses:
        '200':
          description: Webhook received successfully
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_events:DomainVerifiedEvent'
components:
  schemas:
    type_webhooks/events:SvixId:
      type: string
      description: ID of webhook message.
      title: SvixId
    type_webhooks/events:SvixSignature:
      type: string
      description: Signature of webhook message.
      title: SvixSignature
    type_webhooks/events:SvixTimestamp:
      type: string
      format: date-time
      description: Timestamp of webhook message.
      title: SvixTimestamp
    type_events:EventId:
      type: string
      description: ID of event.
      title: EventId
    type_pods:PodId:
      type: string
      description: ID of pod.
      title: PodId
    type_domains:DomainId:
      type: string
      description: The ID of the domain.
      title: DomainId
    type_domains:DomainName:
      type: string
      description: The name of the domain (e.g., `example.com`).
      title: DomainName
    type_domains:VerificationStatus:
      type: string
      enum:
        - NOT_STARTED
        - PENDING
        - INVALID
        - FAILED
        - VERIFYING
        - VERIFIED
      title: VerificationStatus
    type_domains:Status:
      $ref: '#/components/schemas/type_domains:VerificationStatus'
      description: The verification status of the domain.
      title: Status
    type_domains:FeedbackEnabled:
      type: boolean
      description: Bounce and complaint notifications are sent to your inboxes.
      title: FeedbackEnabled
    type_domains:SubdomainsEnabled:
      type: boolean
      description: >-
        Allow inboxes on any subdomain of this domain. Adds a required wildcard
        MX

        record (`*.<domain>`) to `records`.
      title: SubdomainsEnabled
    type_domains:RecordType:
      type: string
      enum:
        - TXT
        - CNAME
        - MX
      title: RecordType
    type_domains:RecordStatus:
      type: string
      enum:
        - MISSING
        - INVALID
        - VALID
      title: RecordStatus
    type_domains:VerificationRecord:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_domains:RecordType'
          description: The type of the DNS record.
        name:
          type: string
          description: The name or host of the record.
        value:
          type: string
          description: The value of the record.
        status:
          $ref: '#/components/schemas/type_domains:RecordStatus'
          description: The verification status of this specific record.
        priority:
          type: integer
          description: The priority of the MX record.
      required:
        - type
        - name
        - value
        - status
      title: VerificationRecord
    type_domains:ClientId:
      type: string
      description: Client ID of domain.
      title: ClientId
    type_domains:Domain:
      type: object
      properties:
        pod_id:
          $ref: '#/components/schemas/type_pods:PodId'
        domain_id:
          $ref: '#/components/schemas/type_domains:DomainId'
        domain:
          $ref: '#/components/schemas/type_domains:DomainName'
        status:
          $ref: '#/components/schemas/type_domains:Status'
        feedback_enabled:
          $ref: '#/components/schemas/type_domains:FeedbackEnabled'
        subdomains_enabled:
          $ref: '#/components/schemas/type_domains:SubdomainsEnabled'
        records:
          type: array
          items:
            $ref: '#/components/schemas/type_domains:VerificationRecord'
          description: |-
            A list of DNS records required to verify the domain. Includes a
            wildcard MX record (`*.<domain>`) when `subdomains_enabled` is true.
        client_id:
          $ref: '#/components/schemas/type_domains:ClientId'
        updated_at:
          type: string
          format: date-time
          description: Time at which the domain was last updated.
        created_at:
          type: string
          format: date-time
          description: Time at which the domain was created.
      required:
        - domain_id
        - domain
        - status
        - feedback_enabled
        - subdomains_enabled
        - records
        - updated_at
        - created_at
      title: Domain
    type_events:DomainVerifiedEvent:
      type: object
      properties:
        type:
          type: string
          enum:
            - event
        event_type:
          type: string
          enum:
            - domain.verified
        event_id:
          $ref: '#/components/schemas/type_events:EventId'
        domain:
          $ref: '#/components/schemas/type_domains:Domain'
      required:
        - type
        - event_type
        - event_id
        - domain
      title: DomainVerifiedEvent

Webhooks ​

Create Webhook ​

OpenAPI Specification ​

Examples ​

Get Webhook ​

OpenAPI Specification ​

Examples ​

List Webhooks ​

OpenAPI Specification ​

Examples ​

Update Webhook ​

OpenAPI Specification ​

Examples ​

Delete Webhook ​

OpenAPI Specification ​

Examples ​

Event: message.received ​

OpenAPI 3.1 Webhook Specification ​

Event: message.sent ​

OpenAPI 3.1 Webhook Specification ​

Event: message.delivered ​

OpenAPI 3.1 Webhook Specification ​

Event: message.bounced ​

OpenAPI 3.1 Webhook Specification ​

Event: message.rejected ​

OpenAPI 3.1 Webhook Specification ​

Event: message.complained ​

OpenAPI 3.1 Webhook Specification ​

Event: domain.verified ​

OpenAPI 3.1 Webhook Specification ​

Webhooks

Create Webhook

OpenAPI Specification

Examples

Get Webhook

OpenAPI Specification

Examples

List Webhooks

OpenAPI Specification

Examples

Update Webhook

OpenAPI Specification

Examples

Delete Webhook

OpenAPI Specification

Examples

Event: message.received

OpenAPI 3.1 Webhook Specification

Event: message.sent

OpenAPI 3.1 Webhook Specification

Event: message.delivered

OpenAPI 3.1 Webhook Specification

Event: message.bounced

OpenAPI 3.1 Webhook Specification

Event: message.rejected

OpenAPI 3.1 Webhook Specification

Event: message.complained

OpenAPI 3.1 Webhook Specification

Event: domain.verified

OpenAPI 3.1 Webhook Specification