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);from mailsai import create_client
client = create_client() # reads MAILS_API_KEY
result = client.create_webhook(
url="https://api.acme.com/webhooks/mails",
event_types=["message.delivered", "reply.received"],
description="Production receiver",
)
print(result)curl -X POST 'https://api.mails.ai/v1/webhooks' \
-H "Authorization: Bearer $MAILS_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"url": "https://api.acme.com/webhooks/mails",
"event_types": ["message.delivered", "reply.received"],
"description": "Production receiver"
}'mails webhooks create https://api.acme.com/hooks/mails \
--event-types message.received,reply.received{
"name": "mails_webhooks_create",
"arguments": {
"url": "https://api.acme.com/webhooks/mails",
"event_types": [
"message.delivered",
"reply.received"
],
"description": "Production receiver"
}
}{
"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"
}201 The created endpoint, including the one-time
signing secret.
400 Invalid request — malformed JSON or a field failed
validation. Also feature_not_enabled when this
server has a feature switched off (custom domains
before they are available).
401 Missing or invalid API key.
403 The API key lacks the required scope
(insufficient_scope), or the token belongs to an
app connected by sign-in and this operation is
closed to connected apps
(connected_app_not_allowed).
422 Unprocessable — agent paused, recipient suppressed,
a recipient at test.mails.ai other than
reply@test.mails.ai (unknown_test_address), or
abuse guard.
500 Internal server error.Create a webhook endpoint
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);from mailsai import create_client
client = create_client() # reads MAILS_API_KEY
result = client.create_webhook(
url="https://api.acme.com/webhooks/mails",
event_types=["message.delivered", "reply.received"],
description="Production receiver",
)
print(result)curl -X POST 'https://api.mails.ai/v1/webhooks' \
-H "Authorization: Bearer $MAILS_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"url": "https://api.acme.com/webhooks/mails",
"event_types": ["message.delivered", "reply.received"],
"description": "Production receiver"
}'mails webhooks create https://api.acme.com/hooks/mails \
--event-types message.received,reply.received{
"name": "mails_webhooks_create",
"arguments": {
"url": "https://api.acme.com/webhooks/mails",
"event_types": [
"message.delivered",
"reply.received"
],
"description": "Production receiver"
}
}{
"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"
}201 The created endpoint, including the one-time
signing secret.
400 Invalid request — malformed JSON or a field failed
validation. Also feature_not_enabled when this
server has a feature switched off (custom domains
before they are available).
401 Missing or invalid API key.
403 The API key lacks the required scope
(insufficient_scope), or the token belongs to an
app connected by sign-in and this operation is
closed to connected apps
(connected_app_not_allowed).
422 Unprocessable — agent paused, recipient suppressed,
a recipient at test.mails.ai other than
reply@test.mails.ai (unknown_test_address), or
abuse guard.
500 Internal server error.Body Parameters
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.
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.
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
Webhook endpoint id (whe_…).
The URL events are POSTed to, as you sent it.
HMAC secret for verifying webhook signatures. SHOWN ONCE.
The event types this endpoint receives: what you sent, or * alone when you left it out.
Your note about the endpoint; null when you sent none.
Always true: a new endpoint starts active. Pause it with active: false on PATCH /v1/webhooks/{id}.
When the endpoint was created (ISO 8601, UTC).
Was this page helpful?