Skip to main content
Your webhook receiver should assume that delivery events are operational data. Store them before running business logic, process them asynchronously, and make handlers idempotent.

​
Success and failure

MailChannels treats a webhook request as successful when your endpoint returns a 2xx HTTP status. Other responses are recorded by status category, including 1xx, 3xx, 4xx, 5xx, and no_response. Use the webhook batch API to inspect recent webhook batches. If no time range is supplied, the API returns batches from the last 3 days. If you provide created_after and created_before, the range must not exceed 31 days. 
#!/usr/bin/env bash
# List webhook batches from the last 3 days.
set -u
: "${MAILCHANNELS_API_KEY:?Set MAILCHANNELS_API_KEY before running}"

curl -X GET "https://api.mailchannels.net/tx/v1/webhook-batch" \
  -H "X-Api-Key: $MAILCHANNELS_API_KEY"

​
Replay failed batches

After you fix a receiver problem, you can resend a specific batch. 
#!/usr/bin/env bash
# Resend a specific webhook batch.
set -u
: "${MAILCHANNELS_API_KEY:?Set MAILCHANNELS_API_KEY before running}"
: "${BATCH_ID:?Set BATCH_ID before running}"

curl -X POST "https://api.mailchannels.net/tx/v1/webhook-batch/$BATCH_ID/resend" \
  -H "X-Api-Key: $MAILCHANNELS_API_KEY"
A successful resend API response means MailChannels made the resend attempt and captured the endpoint response. It does not mean your endpoint returned a 2xx status. Check the response body and your receiver logs.

​
Test delivery

Use webhook validation before production launch and after endpoint changes. Validation sends a test event with your customer handle, a test sender, a test event type, and a generated smtp_id.