Letters and statuses

A letter is a document that CartaFlow prints, puts in an envelope and posts through Correios, the Brazilian national postal service, to an address in Brazil. You create a letter with POST /v1/letters, and it moves through a fixed sequence of statuses until it is posted.

The life of a letterCopy Anchor Link

A letter only moves forward. It starts as scheduled when you schedule it with send_date, or straight as received when you send it right away. It then moves to in_production, printed and posted. While it is scheduled or received, it can still be canceled. If something goes wrong in production, it moves to failed and the amount goes back to your balance.

A status never moves backwards. If a letter has to be printed again in production, for example because the paper jammed in the printer, it joins another print batch and keeps its status.

When each step happenedCopy Anchor Link

The status_transitions field records when the letter reached each status, in UTC. Statuses the letter has not reached are null.

{
  "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
}

• received_at is when the letter was charged. For a letter sent right away it equals created_at. For a scheduled letter it is the send date.
• posted_at is when the letter was handed to Correios. It is the last record of a letter that was sent.
• canceled_at is only set when the letter was canceled, and failed_at when it failed in production.

How to follow a letterCopy Anchor Link

Use webhooks. CartaFlow POSTs to your URL on every status change, and when the letter is changed in the dashboard before production (letter.updated), with the full letter in the body, so you do not need to call the API afterwards.

If you cannot receive webhooks, retrieve the letter with GET /v1/letters/{letter_id}. Production and posting take hours, so polling more than once an hour tells you nothing new. For many letters, use GET /v1/letters with the status filter instead of retrieving them one by one.

curl "https://api.cartaflow.com.br/v1/letters/ltr_8Kq2wX4mN7pR" \
  -H "Authorization: Bearer $CARTAFLOW_API_KEY"

CancelingCopy Anchor Link

You can cancel a letter with POST /v1/letters/{letter_id}/cancel while it is scheduled or received. Nothing is printed.

• A received letter has already been charged. The amount goes back to your balance right away, as a refund transaction.
• A scheduled letter has not been charged yet, so there is nothing to refund.
• From in_production on, the letter is part of a print batch. The API answers 409 with the code letter_not_cancelable, as it also does for a posted or failed letter.
• Canceling a letter that is already canceled returns the same letter, with no error, so retrying the call is safe.

curl -X POST "https://api.cartaflow.com.br/v1/letters/ltr_8Kq2wX4mN7pR/cancel" \
  -H "Authorization: Bearer $CARTAFLOW_API_KEY"

Why a letter was canceledCopy Anchor Link

Every canceled letter carries the reason in cancellation_reason. On other letters the field is null.

Changing before productionCopy Anchor Link

Through the API, a letter does not change after it is created: to change something, cancel it and create another. In the dashboard, under Envios (Letters), people who can send letters can change one before production:

Every change sends the letter.updated event, with the letter as it is now and the same status. Sending a scheduled letter right away sends letter.received.

When production failsCopy Anchor Link

If a letter cannot go out, because the file does not print, because it was damaged and could not be produced again, or because Correios refused it at posting, it moves to failed, a final status, and the amount goes back to your balance automatically, as a refund transaction. You receive the letter.failed event.

The reason is in failure_reason. On other letters the field is null.

To send it again, create a new letter. Problems found before the charge, such as a PDF that breaks the rules or a postal code that does not exist, never reach failed: the API answers 422 at creation and nothing is charged.

Correios servicesCopy Anchor Link

With no choice made, a letter goes as a simple letter ("carta simples"). With the postal_services field you add optional Correios services. Each one costs extra, with its own line in price. See Pricing and balance.

{
  "to": { "name": "Destinatário Exemplo", "postal_code": "01001-000", "number": "128" },
  "document": { "type": "url", "url": "https://arquivos.exemplo.com.br/notificacoes/contrato-5531.pdf" },
  "postal_services": ["registered", "return_receipt"],
  "reference": "contrato-5531"
}

• return_receipt and restricted_delivery only work together with registered. Without it, the API answers 422 with requires_registered and nothing is created.
• The return receipt goes back to the sender: the address you sent in from or, if you did not send one, the account’s default sender. Check that address before using AR. CartaFlow does not receive or scan the receipt.
• In multipart/form-data, repeat the field once per service: postal_services[]=registered and postal_services[]=return_receipt.
• The letter returns your choice in postal_services, always as a list: [] for a simple letter.

After postingCopy Anchor Link

Once posted, the letter is with Correios and delivery follows the postal service. CartaFlow receives no further information about it, so posted is the last status of a letter that was sent. Delivery time depends on the postal service level and the distance to the destination, and CartaFlow does not guarantee it.

• Registered letter: tracking_code carries the Correios tracking code, such as RA123456785BR, from posting on. Use it to follow the delivery with Correios.
• Simple letter: there is no tracking after posting, and tracking_code is null.

When Correios cannot deliver a letter, it goes back to the sender address printed above the recipient. That is the address you sent in from or, if you did not send one, the account’s default sender. See Addresses in Brazil.

The Letter objectCopy Anchor Link

The main fields of a letter. The full list, with the type and description of every field, is in Retrieve a letter.