Cancel a letter that has not yet been dispatched

Endpoint

POST https://api.dairo.app/v1/letters/{id}/cancel

Cancels a letter and returns it with status: "canceled". A letter is cancelable while it is draft, queued, processing, printable, or submitted; once it is in_transit or in a terminal state the call responds 409 with code letter_not_cancelable, and an unknown id is a 404. Cancellation is a status transition, so it emits a letter.status_changed webhook event.

Scope: letters:send. Send the API key as a bearer token; Scopes lists what each one reaches.

Request

cURL

curl -X POST "https://api.dairo.app/v1/letters/3fa85f64-5717-4562-b3fc-2c963f66afa6/cancel" \
  -H "Authorization: Bearer $DAIRO_API_KEY"

Path parameters

Name	Type	Required	Description
`id`	string	yes	The letter's ID.

Response

200 Success. Body: application/json, Letter.

Field	Type	Required	Description
`object`	`"letter"`	yes
`id`	string	yes
`status`	LetterStatus	yes
`fileName`	string or null	no
`pageCount`	integer or null	no
`to`	PostalAddress	no
`from`	PostalAddress or null	no
`print`	LetterPrintOptions	no
`delivery`	LetterDelivery	no
`paperTypes`	array of LetterPaperType	no
`autoSend`	boolean	no
`price`	LetterMoney or null	no
`metadata`	object	no
`lastEventType`	string or null	no	The `type` of the newest event on the letter's timeline (e.g. `processing`, `canceled`); null until the letter has an event.
`lastEventAt`	string (date-time) or null	no	When the newest timeline event occurred; null until the letter has an event.
`submittedAt`	string (date-time) or null	no
`canceledAt`	string (date-time) or null	no
`error`	string or null	no
`createdAt`	string (date-time) or null	no
`updatedAt`	string (date-time) or null	no
`events`	array of LetterEvent	no
`paymentSlip`	`"qr"`, `"sepaDe"`, `"sepaAt"`, `null`	no	The chosen payment-slip overlay, or null for a normal letter.
`dryRun`	boolean	no	True for a validate/price-only letter that is never mailed or charged.
`providerMode`	`"test"`, `"live"`	no	`test`: the letter is validated and priced but never printed, mailed, or charged (a dry run, or the account's provider mode is test). `live`: it will be printed and posted.
`notifications`	boolean	no	Owner milestone-email preference for this letter.
`payment`	LetterPayment or null	no	The structured payment object the slip was generated from (owner records), or null.
`batchId`	string or null	no	The owning batch id for a batch-member letter; null for a single send. Pairs with the `?batchId=` list filter.

200

{
  "object": "letter",
  "id": "string",
  "status": "draft",
  "fileName": "letter.pdf",
  "pageCount": null,
  "to": {
    "name": "Ada Lovelace",
    "company": "Acme GmbH",
    "street": "Hauptstraße",
    "houseNumber": "1",
    "poBox": null,
    "addressLine2": null,
    "postalCode": "10115",
    "city": "Berlin",
    "country": "DE"
  },
  "from": {
    "name": "Ada Lovelace",
    "company": "Acme GmbH",
    "street": "Hauptstraße",
    "houseNumber": "1",
    "poBox": null,
    "addressLine2": null,
    "postalCode": "10115",
    "city": "Berlin",
    "country": "DE"
  },
  "print": {
    "mode": "color",
    "sides": "simplex",
    "addressPlacement": "left"
  },
  "delivery": "economy",
  "paperTypes": [
    "standard"
  ],
  "autoSend": true,
  "price": {
    "currency": "EUR",
    "amount": 0,
    "walletAmount": 0,
    "walletCurrency": "string",
    "walletRate": 0
  },
  "metadata": {},
  "lastEventType": null,
  "lastEventAt": "2026-10-19T09:30:00Z",
  "submittedAt": "2026-10-19T09:30:00Z",
  "canceledAt": "2026-10-19T09:30:00Z",
  "error": null,
  "createdAt": "2026-10-19T09:30:00Z",
  "updatedAt": "2026-10-19T09:30:00Z",
  "events": [
    {
      "object": "letter_event",
      "eventId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "letterId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "type": "string",
      "code": null,
      "description": null,
      "producer": null,
      "location": null,
      "reason": null,
      "hasImage": true,
      "occurredAt": "2026-10-19T09:30:00Z",
      "recordedAt": "2026-10-19T09:30:00Z"
    }
  ],
  "paymentSlip": "qr",
  "dryRun": true,
  "providerMode": "test",
  "notifications": true,
  "payment": {
    "type": "qr",
    "creditor": {
      "name": "Ada Lovelace",
      "iban": "string",
      "bic": null,
      "street": "Hauptstraße",
      "houseNumber": "1",
      "postalCode": "10115",
      "city": "Berlin",
      "country": "DE"
    },
    "amount": 0,
    "currency": "CHF",
    "reference": null,
    "message": null,
    "debtor": {
      "name": "Ada Lovelace",
      "street": "Hauptstraße",
      "houseNumber": "1",
      "postalCode": "10115",
      "city": "Berlin",
      "country": "DE"
    }
  },
  "batchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Errors

Every error has the same body, {"error": {"type", "code", "message", "param"}}; branch on code. Errors lists every code.

Status	Meaning
`400`	The request is malformed or a value is invalid (`invalid_request`, `invalid_domain`, `idempotency_key_mismatch`).
`401`	The API key is missing or invalid.
`403`	The key lacks the scope this endpoint needs (`scope_missing`) or may not do this (`not_permitted`).
`404`	No such resource in this account (`resource_not_found`).
`422`	The request is well-formed but a field failed validation (`validation_failed`).
`429`	Rate limit, plan limit, budget or spend cap reached (`rate_limited`, `plan_limit_reached`, `budget_exceeded`, `spend_cap_reached`).
`500`	An unexpected error; retry with backoff, then contact support (`internal_error`).

Cancel a letter that has not yet been dispatched

Request

Path parameters

Response

Errors

On this page