import { createClient } from "@mailsai/sdk";

const client = createClient(); // reads MAILS_API_KEY

const result = await client.webhooks.test(
  "whe_01JZX8K3M9Q4P7VN2YB6RTDC0E",
);
console.log(result);

from mailsai import create_client

client = create_client()  # reads MAILS_API_KEY

result = client.test_webhook(
    "whe_01JZX8K3M9Q4P7VN2YB6RTDC0E",
)
print(result)

curl -X POST 'https://api.mails.ai/v1/webhooks/whe_01JZX8K3M9Q4P7VN2YB6RTDC0E/test' \
  -H "Authorization: Bearer $MAILS_API_KEY"

mails webhooks test whe_01JABC

{
  "name": "mails_webhooks_test",
  "arguments": {
    "webhook_id": "whe_01JZX8K3M9Q4P7VN2YB6RTDC0E"
  }
}

{
  "webhook_endpoint_id": "whe_01JZX8K3M9Q4P7VN2YB6RTDC0E",
  "event_id": "evt_01JZX8K3M9Q4P7VN2YB6RTDC0E",
  "delivery_id": "whd_01JZX8K3M9Q4P7VN2YB6RTDC0E",
  "ok": false,
  "http_status": 0,
  "response_excerpt": "<response_excerpt>"
}

200  The test delivery result.
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).
404  Resource not found in this workspace, or the agent
     a send names is archived (agent_archived).
429  Rate or quota limit exceeded. The body's resets_at
     and retry_after_seconds say when the request can
     succeed. A Retry-After header is sent only when
     that is 60 seconds or less; a longer wait (an
     hourly, daily or monthly cap) sends none, so retry
     at resets_at or raise the limit instead of
     sleeping.
500  Internal server error.

Send a test event

Fires a synthetic webhook.test event at the endpoint and reports the delivery result.

POST/v1/webhooks/{id}/testscope · manage

import { createClient } from "@mailsai/sdk";

const client = createClient(); // reads MAILS_API_KEY

const result = await client.webhooks.test(
  "whe_01JZX8K3M9Q4P7VN2YB6RTDC0E",
);
console.log(result);

from mailsai import create_client

client = create_client()  # reads MAILS_API_KEY

result = client.test_webhook(
    "whe_01JZX8K3M9Q4P7VN2YB6RTDC0E",
)
print(result)

curl -X POST 'https://api.mails.ai/v1/webhooks/whe_01JZX8K3M9Q4P7VN2YB6RTDC0E/test' \
  -H "Authorization: Bearer $MAILS_API_KEY"

mails webhooks test whe_01JABC

{
  "name": "mails_webhooks_test",
  "arguments": {
    "webhook_id": "whe_01JZX8K3M9Q4P7VN2YB6RTDC0E"
  }
}

{
  "webhook_endpoint_id": "whe_01JZX8K3M9Q4P7VN2YB6RTDC0E",
  "event_id": "evt_01JZX8K3M9Q4P7VN2YB6RTDC0E",
  "delivery_id": "whd_01JZX8K3M9Q4P7VN2YB6RTDC0E",
  "ok": false,
  "http_status": 0,
  "response_excerpt": "<response_excerpt>"
}

200  The test delivery result.
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).
404  Resource not found in this workspace, or the agent
     a send names is archived (agent_archived).
429  Rate or quota limit exceeded. The body's resets_at
     and retry_after_seconds say when the request can
     succeed. A Retry-After header is sent only when
     that is 60 seconds or less; a longer wait (an
     hourly, daily or monthly cap) sends none, so retry
     at resets_at or raise the limit instead of
     sleeping.
500  Internal server error.

Path Parameters

idstringrequired

Webhook endpoint id.

Response

webhook_endpoint_idstring

The endpoint the test event was sent to: the id in the path. A paused endpoint is sent it too.

event_idstring

Id of the webhook.test event that was sent (evt_…). It is stored with test_mode true, and GET /v1/events/{id} returns it.

delivery_idstring

Id of this test's delivery record (whd_…), listed by GET /v1/webhooks/{id}/deliveries. A failed test is not retried.

okboolean

True when the endpoint answered with a 2xx status.

http_statusinteger | null

The status the endpoint answered with, after following up to 3 redirects. Null when no answer came: a connection error, no answer within 5 seconds, or an address that is not public.

response_excerptstring

The first 500 characters of the endpoint's response body; when no answer came, the reason instead.

Was this page helpful?