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:Verifying Webhooks
To ensure webhooks are genuinely from MailBreeze, verify the signature header.Signature Header
Every webhook includes anX-MailBreeze-Signature header:
t— Unix timestamp when the signature was generatedv1— 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 with200 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:Testing Webhooks
Local Development
Use a tunneling service to expose your local server:ngrok
Test Endpoint
Send a test webhook from the MailBreeze dashboard:- Go to Domains > your domain > Inbound Settings > Routes
- Select your webhook route
- Click Send Test Webhook
Manual Testing
Send an email to an address on your domain and monitor your endpoint logs.Error Handling
Return appropriate HTTP status codes: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