Webhook Payloads

When MXHook routes an email to your application, it delivers a structured JSON payload via HTTP POST.

Payload Format

{
  "message_id": "<abc123@example.com>",
  "from": "sender@example.com",
  "to": ["recipient@yourdomain.com"],
  "subject": "Hello from MXHook",
  "text_body": "Plain text content of the email.",
  "html_body": "<p>HTML content of the email.</p>",
  "headers": {
    "From": "sender@example.com",
    "To": "recipient@yourdomain.com",
    "Subject": "Hello from MXHook",
    "Date": "Wed, 19 Mar 2025 12:00:00 +0000",
    "Message-ID": "<abc123@example.com>",
    "MIME-Version": "1.0",
    "Content-Type": "multipart/mixed"
  },
  "attachments": [
    {
      "filename": "report.pdf",
      "content_type": "application/pdf",
      "size": 24680,
      "content": "base64-encoded-content..."
    }
  ]
}

Fields

Field	Type	Description
message_id	string	The email's Message-ID header
from	string	Sender's email address
to	string[]	List of recipient addresses
subject	string	Email subject line
text_body	string	Plain text body (may be empty)
html_body	string	HTML body (may be empty)
headers	object	All email headers as key-value pairs
attachments	array	List of attachments (see Attachments)

HTTP Request

MXHook sends the payload as:

POST /your-webhook-path HTTP/1.1
Host: yourapp.com
Content-Type: application/json
X-MXHook-Signature: sha256=abc123...

Headers

Header	Description
Content-Type	Always application/json
X-MXHook-Signature	HMAC-SHA256 signature (present if webhook secret is configured)

Expected Response

MXHook considers delivery successful when your endpoint returns a 2xx status code. Any other status code triggers a retry.

Response	Behavior
200-299	Delivery marked as successful
400-499	Retried (may be a transient issue)
500-599	Retried with exponential backoff
Timeout	Retried (default timeout: 30 seconds)

Retry Behavior

Failed deliveries are retried with exponential backoff:

Attempt	Delay
1st retry	~1 minute
2nd retry	~5 minutes
3rd retry	~15 minutes

After all retry attempts are exhausted (default: 3), the message is moved to the dead letter queue.