# 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.

| Response                    | Behavior                                        |
| --------------------------- | ----------------------------------------------- |
| `200`–`299`                 | Acknowledge delivery.                           |
| Connection error or timeout | Retry while the delivery window remains open.   |
| `408`, `429`, `500`–`599`   | Retry with exponential backoff and jitter.      |
| Redirect or other status    | Mark failed. Investigate and explicitly replay. |

```mermaid
flowchart TD
    A[Send attempt] --> B{Receiver response}
    B -->|2xx| D[Delivered]
    B -->|Timeout, connection error, 408, 429, or 5xx| W[Back off]
    W --> C{Delivery window open?}
    C -->|Yes| A
    C -->|No| F[Failed]
    B -->|Redirect or other status| F
    F --> X[Fix receiver 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.

```mermaid
flowchart LR
    A[Automatic delivery window] --> B[Several attempts may occur]
    B --> C[Same event ID and pinned shaping revision]
    B --> D[New attempt ID and signature timestamp each time]
    B --> E[Failed: fix receiver, then explicitly replay]
    E --> F[Replay requests another delivery window]
    X[Current content expiry] -. bounds both windows .-> A
    X -. remains the hard limit .-> F
    Y[Destination revision captured at acceptance] -. remains pinned .-> F
```

API keys need `deliveries:replay`:

```bash
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.
