Skip to main content
import { createClient } from "@mailsai/sdk";

const client = createClient(); // reads MAILS_API_KEY

const result = await client.webhooks.create({
  url: "https://api.acme.com/webhooks/mails",
  event_types: ["message.delivered", "reply.received"],
  description: "Production receiver",
});
console.log(result);
{
  "id": "whe_01JZXC6Q8S0U2W4Y6A8C0E2G4J",
  "url": "https://api.acme.com/webhooks/mails",
  "signing_secret": "whsec_8f3a1c5e7b9d2f4a6c8e0b2d4f6a8c0e",
  "event_types": ["message.delivered", "reply.received"],
  "description": "Production receiver",
  "active": true,
  "created_at": "2026-06-24T17:40:00.000Z"
}

Create a webhook endpoint

Registers an HTTPS endpoint to receive events.
POST/v1/webhooksscope · manage
import { createClient } from "@mailsai/sdk";

const client = createClient(); // reads MAILS_API_KEY

const result = await client.webhooks.create({
  url: "https://api.acme.com/webhooks/mails",
  event_types: ["message.delivered", "reply.received"],
  description: "Production receiver",
});
console.log(result);
{
  "id": "whe_01JZXC6Q8S0U2W4Y6A8C0E2G4J",
  "url": "https://api.acme.com/webhooks/mails",
  "signing_secret": "whsec_8f3a1c5e7b9d2f4a6c8e0b2d4f6a8c0e",
  "event_types": ["message.delivered", "reply.received"],
  "description": "Production receiver",
  "active": true,
  "created_at": "2026-06-24T17:40:00.000Z"
}

Body Parameters

urlstringrequired

The https:// URL events are POSTed to. Its host must resolve to public IP addresses only. A host that does not resolve, or resolves to a private, loopback or link-local address, is refused with 400 invalid_param_value.

event_typesstring[]

Events to deliver, at least one. "*" is every event except thread.created, thread.updated, thread.deleted and message.delayed, sent only to an endpoint that names them.

Default: ["*"]

descriptionstring

A note of your own to tell endpoints apart, up to 255 characters. Left out, description is null.

The signing_secret is returned ONCE — use it to verify signatures. An empty event_types list is refused with 422 invalid_param_value: an endpoint with no event types would never be sent anything. Closed to apps connected by sign-in (403 connected_app_not_allowed): use the dashboard, an API key or the mails CLI.

Response

idstring

Webhook endpoint id (whe_…).

urlstring

The URL events are POSTed to, as you sent it.

signing_secretstring

HMAC secret for verifying webhook signatures. SHOWN ONCE.

event_typesstring[]

The event types this endpoint receives: what you sent, or * alone when you left it out.

descriptionstring | null

Your note about the endpoint; null when you sent none.

activeboolean

Always true: a new endpoint starts active. Pause it with active: false on PATCH /v1/webhooks/{id}.

created_atstring

When the endpoint was created (ISO 8601, UTC).

Was this page helpful?