Free retry of failed bulk items API
Run the items of a paid bulk request that failed for technical reasons again, free of charge.
POST https://api.probekit.dev/v1/mail/check/bulk/retry
Updated 2026-10-09
How it works
- A paid bulk response where items failed for a technical reason holds a retry_token.
- Only those items are run again, with the domains from the paid request. The input cannot be changed.
- Nothing is charged, and no payment header is needed.
- A token is valid for 15 minutes from when it was issued and for 3 attempts in total.
- Each attempt that still has failed items returns a new token, and the old one stops working.
- Lost the answer? Send the paid bulk request again with the same PAYMENT-SIGNATURE: the redelivered result holds the newest token, and earlier tokens stop working.
- An attempt answered with 503 does not count.
Input
A JSON body with content-type: application/json. Send it without a PAYMENT-SIGNATURE header.
| Name | Type | Required | Limits | Description |
|---|---|---|---|---|
retry_token | string | Yes | 16–256 characters | The retry_token from a paid bulk response with failed items. |
Example request
curl -i -X POST https://api.probekit.dev/v1/mail/check/bulk/retry \
-H 'content-type: application/json' \
-d '{"retry_token": "Ex4mpleRetryToken_doNotUse-0123456789abcdef"}'Response
The same format as the Bulk mail configuration check API, with the retried items merged in at their original positions.
| Field | Meaning |
|---|---|
request_id | Unique id of this request. Quote it when you contact support. |
endpoint | The endpoint id, mail.check.bulk. |
schema_version | Version of the response format, currently 1.0. |
checked_at | When the batch ran (ISO 8601, UTC). |
results | One entry per input item, in input order: index, item, and either result (a full check response) or error. |
item_count | Number of items in the request. |
succeeded_count | Items with a result. |
failed_count | Items that failed for a technical reason. |
retry_token | Present when items failed for a technical reason: send it to /v1/mail/check/bulk/retry within 15 minutes to run those items again free of charge (3 attempts in total). Otherwise null. |
Status codes
| Status | Code | Meaning | Do you pay? |
|---|---|---|---|
| 200 | — | The bulk result with the retried items merged in. It holds a new retry_token while items still fail and attempts are left. | No |
| 400 | bad_request | The request is malformed. | No |
| 404 | retry_token_invalid | The retry token is unknown, or a newer token from a later attempt has replaced it. | No |
| 409 | retry_in_progress | An attempt with this retry token is already running. | No |
| 410 | retry_token_expired | The retry token has expired (15 minutes after it was issued), all 3 attempts are used, or no failed items are left. | No |
| 413 | payload_too_large | The body is larger than 64 KB. | No |
| 422 | invalid_input | The body is invalid: it must hold only retry_token. | No |
| 429 | rate_limited | Too many requests from this IP address. | No |
| 503 | busy, unavailable | The service is busy or temporarily unavailable. The attempt does not count. | No |
Errors use the common error body. See errors.