>_SMTPBoxDOCUMENTATION

SMTPBox email webhooks and signature verification

Receive message.received events, verify the SMTPBox-Signature header and handle retries safely.

10 / EVENTS

React to captured messages

Add an HTTPS endpoint in the dashboard. SMTPBox sends a message.received event after the message has been processed. Return any 2xx status promptly.

Verify SMTPBox-Signature
<?php

$body = file_get_contents('php://input');
$signature = $_SERVER['HTTP_SMTPBOX_SIGNATURE'] ?? '';
if (!preg_match('/^t=(\d+),v1=([a-f0-9]{64})$/', $signature, $matches)) {
    http_response_code(401);
    exit;
}

$expected = hash_hmac('sha256', $matches[1] . '.' . $body, $secret);
$valid = abs(time() - (int) $matches[1]) <= 300
    && hash_equals($expected, $matches[2]);

http_response_code($valid ? 204 : 401);

The signing secret is shown once. Failed deliveries are retried after approximately 1 minute, 5 minutes, 30 minutes and 2 hours before being marked failed. Design handlers to be idempotent in case an event arrives more than once.

Updated