Delivery & retries

After Repost accepts a message, each subscribed endpoint gets its own delivery, with its own attempt history, schedule, and status. One customer's dead endpoint never affects another's, and a message to three endpoints is three independent deliveries.

What counts as delivered#

A delivery attempt is an HTTPS POST of the signed envelope to the endpoint URL. A 2xx response completes the delivery. Anything else is a failure: 4xx, 5xx, timeouts, connection errors, and also 3xx, because redirects are never followed. Following one would replay a signature to a location the customer didn't register.

The body Repost sends is the body you published, byte for byte. It is not re-serialized on the way through, and a replay or a redelivery sends the same bytes again, so a receiver that hashes or dedupes on the raw body sees the same message every time.

The retry schedule#

A failing delivery is tried 11 times: the first attempt plus ten retries. Each retry waits a base delay plus a jitter of between half and one base delay, so retries don't arrive in herds at a recovering endpoint. The wait is measured from when the previous attempt actually ran, not from when it was scheduled, so an attempt that ran late still gets a full gap before the next one.

End to end that is between about 36 and 47 hours. If the endpoint responds with a Retry-After header longer than the scheduled wait, Repost honours it, counted from the moment the endpoint answered, up to a cap of one hour. When the last retry fails, the delivery moves to the dead-letter queue with its full attempt history and the reason exhausted.

An endpoint can carry its own schedule instead: set retryPolicy to {"version": 1, "delaysMs": [...]} when creating or updating it, with 1 to 20 base delays of 1 second to 24 hours each. The same jitter rule applies to each delay.

Endpoint state changes cut the schedule short instead of wasting attempts. Pausing an endpoint holds its deliveries, including retries that come due while it is paused, until you resume it. Disabling one fails its deliveries terminally as endpoint_disabled, and deleting one fails them, held ones included, as endpoint_gone. Updating an endpoint's URL or headers applies to pending retries too.

Delivery statuses#

A failed or dlq delivery carries a failureReason:

Deliveries can be listed and inspected over the API, in the dashboard's Messages view, or by the customer in their portal:

Copycurl "https://api.repost.sh/v1/deliveries?status=dlq&limit=50" \
  -H "Authorization: Bearer $REPOST_TOKEN"
 
curl "https://api.repost.sh/v1/messages/msg_01JZX.../deliveries" \
  -H "Authorization: Bearer $REPOST_TOKEN"

The message route lists every generation of every delivery, oldest first. The status=dlq list, the dead-letter queue counts, and the portal's DLQ leave out any delivery that a later replay generation has superseded, so a replayed dead letter stops counting as one the moment its replay is queued.

Attempt logs#

Every attempt is recorded: the response status, latency, an error class such as TIMEOUT or CONNECTION_FAILED, and a bounded excerpt of the response body and headers (up to 4 KiB each). Sensitive request headers are stored as [redacted]; only content-type, user-agent, webhook-id, and webhook-timestamp are kept verbatim, and Set-Cookie response headers are dropped. There is enough to debug a failing endpoint without secrets ending up in logs.

The delivery detail in the dashboard and the portal shows the request and the response of each attempt, and the attempt log streams live, so a retry or a replay shows up as it happens. Attempts are labelled by generation and attempt number: #0, #1, #2 for the original delivery, g1 #0 for the first attempt of its first replay, and so on.

Customers see the same attempt history for their own endpoints, live, in the portal.

Replay and redeliver#

A delivery in the dead-letter queue is not lost. Replay it with one call, or re-send an already-delivered message to a specific endpoint, for example after a customer restores from a backup:

Copy# Replay a delivery
curl -X POST https://api.repost.sh/v1/deliveries/{deliveryId}/replay \
  -H "Authorization: Bearer $REPOST_TOKEN"
 
# Redeliver a message to one endpoint
curl -X POST https://api.repost.sh/v1/messages/{messageId}/redeliver \
  -H "Authorization: Bearer $REPOST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"endpointId": "..."}'

Both answer 202 with {"queued": true, "deliveryId": "dl_..."}. The new delivery is a new generation of the same message and endpoint: it re-enters the normal pipeline with the published bytes, signed with the endpoint's current secrets, and its attempts are recorded like any other. Delivery ids are deterministic, so the same message, endpoint and generation always name the same delivery. The new generation supersedes the one it replays: lists and the dead-letter queue count show the newest generation as the outcome for that message and endpoint, and the older one reads as superseded. Redelivering a message to an endpoint does the same for that endpoint's latest generation.

Replay is guarded. A second replay or redelivery of the same message and endpoint inside 10 minutes sends nothing and answers 409 with reason: "duplicate" and the deliveryId of the replay already queued; the dashboard, the portal and the CLI say the same. The other refusals:

Customers can replay their own dead-lettered deliveries from the portal.

Bulk replay#

To replay many deliveries at once, the dashboard, the portal, the CLI (repost send replays) and the agent operations run a replay job against one endpoint. The job goes through the same steps everywhere:

1. Estimate. Pick a selection: failed and dead-lettered deliveries in a time window (the portal's Recover failed messages), a status filter, or a query. Repost counts what matches.
2. Prepare. The selection is frozen into a manifest with a fixed upper bound and total, so what you confirm is what runs.
3. Confirm. Confirmation is bound to that manifest; a selection that changed since is rejected before anything is sent.
4. Run. Generations are handed to the endpoint at the rate you chose. An item reads queued until its attempt lands, so the job can report every item sent while the endpoint is still receiving.
5. Settle. Once the endpoint has answered every generation, the job reports how many were delivered, dead-lettered and failed. The outcomes add up to the manifest total.

Cancelling a job stops dispatch. Generations already handed to the endpoint finish normally; the ones never attempted read failed · job_cancelled, and a cancelled generation supersedes nothing, so a delivery that had already succeeded keeps success as its outcome. An endpoint runs one job at a time, and pausing the endpoint pauses its job.

Continue#