Skip to main content

Delivery, retries, and replay

For messages with positive retention, Wildmail retries eligible delivery failures within the delivery and retention window. Messages with 0-day retention allow at most one HTTP attempt and cannot be retried or replayed. Processing failures, invalid payload mappings, disabled destinations, or expiry can prevent an HTTP attempt.

Persist the signed wildmail-event-id header atomically with your business changes so retries cannot apply the same action twice. A network failure after your application commits may cause another attempt for a retained message.

Endpoint responses​

These retry rules apply to messages with positive retention. A 0-day message is never retried, including after a timeout, 429, or server error.

ResponseBehavior
200–299Acknowledge delivery.
Connection error or timeoutRetry while the delivery window remains open.
408, 429, 500–599Retry with exponential backoff and jitter.
Redirect or other statusMark failed. Investigate and explicitly replay.

Connection establishment is limited to five seconds. An HTTP attempt has a fifteen-second overall deadline, and Wildmail reads at most 64 KiB of its response body. A received 2xx status acknowledges delivery even if the response body later exceeds the limit or cannot be read completely. Return a small response promptly after a durable application commit or durable enqueue.

Automatic retries start at a minimum of ten seconds and back off to a one-hour base interval. Valid Retry-After values are respected. If the requested delay exceeds the delivery deadline, the event fails rather than retrying earlier. Automatic delivery ends after 24 hours or content expiry, whichever occurs first.

Every attempt has a new attempt ID and signature timestamp. The event ID, endpoint, and shaping revision remain pinned. Retries preserve the request body. Delivery stops if the same event can no longer be rendered with identical bytes. SMTP retransmission creates a separate stored message and may create a separate event. Message-ID is sender-supplied and is unsuitable as a universal deduplication key.

Inspect and replay​

Open Deliveries, select a delivery, inspect its status and content-free attempt history, then choose Replay after fixing the receiving application. Replay keeps the same event ID and pinned endpoint and shaping revision. Replay does not consume additional inbound message allowance. Messages with 0-day retention cannot be replayed.

API keys need deliveries:replay:

curl --fail-with-body -X POST \
"$WILDMAIL_BASE_URL/api/deliveries/$DELIVERY_ID/replay" \
-H "Authorization: Bearer $WILDMAIL_API_KEY"

An in-progress delivery attempt can cause 409 because another attempt is in flight. An inactive endpoint also needs correction before replay. Expired content produces 410. Retrying the replay request cannot extend retention.

Current events preserve the endpoint revision captured at acceptance, including its URL and payload mapping. Editing either changes new messages. Retained deliveries keep their pinned endpoint and mapping. Replay does not apply a newer mapping. Changing a mapping does not repair an existing event that uses an invalid pinned mapping. Correct the mapping for future email and send a new message.

Keep your application's deduplication records at least as long as the replay window. Replaying an event already applied successfully should acknowledge the duplicate without repeating side effects.