Docs
Events

Retrieve an event

Returns one event.

GET
/events/{event_id}

Authorization

apiKey
headerAuthorizationBearer <token>

API key in the Authorization: Bearer cf_live_... header. Create and revoke keys in the dashboard, under Desenvolvedores > Chaves de API (Developers > API keys).

Path Parameters

event_id*string

The event id, starting with evt_.

Response Body

The event.

application/json
  1. response

Something that happened in your account, such as a letter being posted. CartaFlow sends each event to your webhooks and keeps it for 30 days.

id*string

Unique identifier of the event. It is the same value as the webhook-id header: use it to ignore repeated deliveries. Always starts with evt_.

Match^evt_[A-Za-z0-9]+$
object*string

Object type. Always event.

type*string

What happened. Every status change creates an event named object.new_status; a letter changed in the dashboard before production, without changing status, creates letter.updated.

Possible values

  • letter.scheduled: A letter was scheduled with send_date. It has not been charged yet.
  • letter.received: A letter was charged and joined the production queue: right after creation or, if it was scheduled, on its send date. Covers letters created through the API and the dashboard.
  • letter.in_production: The letter joined a print batch and can no longer be canceled.
  • letter.printed: The letter was printed and enveloped.
  • letter.posted: The letter was handed to Correios. It is the last event of a letter that was sent.
  • letter.canceled: The letter was canceled. Check cancellation_reason: requested when you canceled it, insufficient_balance when a scheduled letter could not be charged on its date.
  • letter.failed: The letter failed in production and will not be posted. The amount went back to the balance automatically. Check failure_reason.
  • letter.updated: The letter was changed in the dashboard before production, without changing status: send date, address, file, variables, printing, Correios services or reference. data carries the letter as it is now. When the change altered the price of a scheduled letter, price has the new amount.
  • verification.received: A verification was created, through the API or the dashboard (see source), and the letter with the code is in the production queue.
  • verification.in_production: The letter with the code is being printed. From here on, canceling revokes the verification, with no refund.
  • verification.awaiting_code: The letter with the code was posted. The person can confirm once it arrives.
  • verification.verified: The person confirmed the right code. The address is verified.
  • verification.failed: 5 wrong codes were entered and the verification was locked.
  • verification.expired: The person did not confirm the code within 60 days of posting.
  • verification.canceled: The verification was canceled before posting, by you or by CartaFlow, and the amount went back to the balance.
  • verification.revoked: You canceled the verification after production started. The code stopped working and the amount does not go back to the balance. If it was verified, treat the address as not verified.
Value in"letter.scheduled""letter.received""letter.in_production""letter.printed""letter.posted""letter.canceled""letter.failed""letter.updated""verification.received""verification.in_production""verification.awaiting_code""verification.verified""verification.failed""verification.expired""verification.canceled""verification.revoked"
data*|

The full object as it was right after the event: a letter for letter.* events and a verification for verification.* events.

created_at*string

When the event happened.

Formatdate-time
curl "https://api.cartaflow.com.br/v1/events/string" \  -H "Authorization: Bearer $CARTAFLOW_API_KEY"
{  "id": "evt_6Tq1Yz8Wm3Rb",  "object": "event",  "type": "letter.posted",  "data": {    "id": "ltr_8Kq2wX4mN7pR",    "object": "letter",    "status": "posted",    "to": {      "name": "Destinatário Exemplo",      "street": "Praça da Sé",      "number": "128",      "complement": "Ap. 52",      "neighborhood": "Sé",      "city": "São Paulo",      "state": "SP",      "postal_code": "01001-000"    },    "from": {      "name": "Exemplo Serviços Ltda.",      "street": "Avenida Exemplo",      "number": "1000",      "complement": "Sala 301",      "neighborhood": "Bela Vista",      "city": "São Paulo",      "state": "SP",      "postal_code": "01310-100"    },    "document": {      "type": "url",      "url": "https://arquivos.exemplo.com.br/faturas/2026-10-0042.pdf",      "variables": null    },    "color": true,    "double_sided": false,    "address_placement": "first_page",    "postal_services": [],    "pages": 2,    "sheets": 2,    "price": {      "currency": "BRL",      "total": 1135,      "items": [        {          "type": "base",          "quantity": 1,          "unit_amount": 990,          "amount": 990        },        {          "type": "additional_sheets",          "quantity": 1,          "unit_amount": 75,          "amount": 75        },        {          "type": "color",          "quantity": 2,          "unit_amount": 35,          "amount": 70        }      ]    },    "send_date": null,    "cancellation_reason": null,    "failure_reason": null,    "tracking_code": null,    "preview_url": "https://files.cartaflow.com.br/previews/ltr_8Kq2wX4mN7pR.pdf?expires=1760369400&signature=9c1f2a7d",    "reference": "fatura-2026-10-0042",    "metadata": {      "customer_id": "1842"    },    "status_transitions": {      "received_at": "2026-10-13T14:20:00Z",      "in_production_at": "2026-10-13T21:00:00Z",      "printed_at": "2026-10-14T10:42:00Z",      "posted_at": "2026-10-14T16:05:00Z",      "canceled_at": null,      "failed_at": null    },    "created_at": "2026-10-13T14:20:00Z"  },  "created_at": "2026-10-14T16:05:00Z"}

List events GET

Returns the events of the last 30 days, newest first.

Letter events Webhook

CartaFlow POSTs to your webhook URL on every status change of a letter, and with `letter.updated` when it is changed in the dashboard before production, with the event in the body.