Skip to main content
When you configure a webhook destination for inbound email, MailBreeze sends a POST request to your endpoint with the full email data. This allows you to parse emails, extract information, trigger workflows, and integrate with your application.

Webhook Payload

MailBreeze sends a JSON payload with the complete email data:

Payload Fields

string
Unique identifier for this inbound email.
string
Event type. Always inbound.received for new emails.
string
ISO 8601 timestamp when the webhook was sent.
object
Sender information with address and name fields.
array
Array of recipient objects matching your domain.
array
Array of CC recipient objects.
string
Email subject line.
string
Plain text body of the email.
string
HTML body of the email (if present).
array
Array of attachment objects with metadata and download URLs.
object
Key email headers including Message-ID, Date, In-Reply-To, and References.
object
SPF, DKIM, and DMARC check results (pass, fail, none).
number
Spam score from 0.0 (not spam) to 1.0 (definitely spam).

Webhook Requirements

Your endpoint must meet these requirements:
If your endpoint returns a non-2xx status code or times out, MailBreeze will retry the webhook. See Retry Behavior below.

Verifying Webhooks

To ensure webhooks are genuinely from MailBreeze, verify the signature header.

Signature Header

Every webhook includes an X-MailBreeze-Signature header:
The header contains:
  • t — Unix timestamp when the signature was generated
  • v1 — HMAC-SHA256 signature of the payload

Verification Steps

1

Extract the timestamp and signature

Parse the header to get t (timestamp) and v1 (signature).
2

Prepare the signed payload

Concatenate the timestamp and raw request body with a period.
3

Compute expected signature

Calculate HMAC-SHA256 using your webhook secret.
4

Compare signatures

Use timing-safe comparison to prevent timing attacks.
5

Validate timestamp

Reject requests older than 5 minutes to prevent replay attacks.

Complete Verification Example

Retry Behavior

If your endpoint fails to respond with 200 OK, MailBreeze retries with exponential backoff: After 7 failed attempts, the webhook is marked as failed. Failed webhooks are visible in Domains > Inbound > Delivery Logs.
Your endpoint should handle duplicate deliveries gracefully. Use the id field to deduplicate emails in case a webhook is retried despite successful processing.

Downloading Attachments

Attachment URLs require authentication. Include your API key when downloading:
Attachment URLs expire after 7 days. Download attachments promptly if you need to retain them.

Testing Webhooks

Local Development

Use a tunneling service to expose your local server:
ngrok

Test Endpoint

Send a test webhook from the MailBreeze dashboard:
  1. Go to Domains > your domain > Inbound Settings > Routes
  2. Select your webhook route
  3. Click Send Test Webhook
This sends a sample payload to verify your endpoint is working.

Manual Testing

Send an email to an address on your domain and monitor your endpoint logs.

Error Handling

Return appropriate HTTP status codes:
If you need more time to process an email, return 200 OK immediately and process asynchronously. Use a message queue (Redis, SQS, etc.) for heavy processing.

Common Patterns

Parse Reply-To Thread

Extract the thread ID from reply-to addresses:

Filter Spam

Use the spam score and authentication results:

Extract Thread Context

Use headers for conversation threading:

Next Steps

Configure Routes

Set up address-specific routing rules

Inbound API

Retrieve inbound emails via API