API reference

Deliveries

Re-deliver a stored message to its webhook. See Delivery & reliability for a guided walk-through.

Auth: Session token · Base URL: https://api.mailkite.dev

Endpoints

Each row expands to its request and response schema. The address bar follows along, so any endpoint can be linked to directly.

POST /api/deliveries/:id/retry Re-deliver a stored message to its webhook.

Re-deliver a stored message to its webhook.

Response body

retry-delivery-response.json

POST /api/deliveries/:id/retry — the outcome and the NEW delivery row the retry appended (history is append-only; the original row is untouched).

Field	Type	Notes
ok req	boolean	The endpoint accepted the redelivery.
status req	integer	HTTP status the endpoint returned (0 when the request failed before a response).
delivery req	delivery	The new delivery row recording this retry.
delivery.id req	string	Delivery id (dlv_…).
delivery.message_id req	string	The message this delivery carries (msg_…).
delivery.route_id req	string	The route whose webhook was targeted (rte_…).
delivery.url req	string	The webhook URL the body was POSTed to.
delivery.status req	"pending" · "delivered" · "failed" · "paused"	Current state of this delivery.
delivery.attempts req	integer	How many attempts this delivery has made.
delivery.last_status_code	integer · null	HTTP status of the most recent attempt.
delivery.next_retry_at	integer · null	When the auto-retry cron will re-attempt a failed delivery; null when nothing is due, in Unix epoch milliseconds (UTC); null when it has never happened.
delivery.retry_attempts	integer	How many automatic retries have been scheduled so far.
delivery.created_at req	integer	When the delivery was created, in Unix epoch milliseconds (UTC).
delivery.updated_at req	integer	When the delivery last changed, in Unix epoch milliseconds (UTC).

An actual response, recorded from the conformance suite.

response.json

{
  "ok": true,
  "status": 200,
  "delivery": {
    "id": "dlv_7Mn3PxQb",
    "message_id": "msg_2Hk9QpVn4tLd",
    "route_id": "rte_4Bn8XcVm",
    "url": "https://myapp.ai/hooks/mailkite",
    "status": "delivered",
    "attempts": 2,
    "last_status_code": 200,
    "created_at": 1769817600000,
    "updated_at": 1769817600000
  }
}

retry-delivery-response.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://api.mailkite.dev/v1/schemas/retry-delivery-response.json",
  "title": "Retry delivery response",
  "description": "POST /api/deliveries/:id/retry — the outcome and the NEW delivery row the retry appended (history is append-only; the original row is untouched).",
  "type": "object",
  "required": [
    "ok",
    "status",
    "delivery"
  ],
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "The endpoint accepted the redelivery."
    },
    "status": {
      "type": "integer",
      "description": "HTTP status the endpoint returned (0 when the request failed before a response).",
      "examples": [
        200
      ]
    },
    "delivery": {
      "$ref": "delivery.json",
      "description": "The new delivery row recording this retry."
    }
  }
}