Retrieve a letter

Unique identifier of the letter. Always starts with ltr_.

Object type. Always letter.

Where the letter is. It only moves forward, never back: scheduled (only when scheduled), received, in_production, printed, posted. From scheduled or received it can move to canceled; from received, in_production or printed, to failed. A reprint in production does not change the status.

Possible values

• scheduled: The letter was validated and is waiting for its send_date. It has not been charged yet. On that date, at 06:00 Brasília time, CartaFlow debits the balance and the letter moves to received. If the balance does not cover the price, it moves to canceled. It can be canceled at no cost.
• received: CartaFlow validated the document and the address, charged the letter to your balance and put it in the production queue. It can still be canceled, and the amount goes back to the balance.
• in_production: The letter is part of a print batch. From this point on it can no longer be canceled.
• printed: The letter was printed, folded and put in its envelope. Posting is the next step.
• posted: The letter was handed to Correios, the Brazilian postal service. From here on delivery follows the postal service, and CartaFlow receives no further updates about it. A registered letter carries its Correios tracking code in tracking_code.
• canceled: The letter was canceled before production and nothing was printed. cancellation_reason says why: you canceled it, or the balance did not cover a scheduled letter on its send date. If it had been charged, the amount went back to the balance.
• failed: Something went wrong in production and the letter will not be posted. failure_reason says why. The amount went back to the balance automatically.

Recipient.

Sender printed above the recipient: the one you sent or the account’s default sender.

Where the letter content came from. The final PDF is at preview_url.

true when printed in color.

true when printed on both sides.

Where the address is printed.

Possible values

• first_page: In the address area of the document’s first page.
• extra_page: On a side of its own, the first one, at no charge.

The optional Correios services chosen at creation. Always a list: [] for a simple letter ("carta simples").

Possible values

• registered: Registered letter ("carta registrada"): the letter is posted with registration at Correios and gets a Correios tracking code, shown in tracking_code once it is posted.
• return_receipt: Return receipt ("aviso de recebimento", AR): Correios returns a card signed by whoever received the letter to the sender printed on the envelope. Requires registered.
• restricted_delivery: Restricted delivery ("mão própria", MP): Correios delivers only to the person named on the envelope. Requires registered.

Number of pages in your document, not counting the address side with extra_page.

Sheets of paper in the envelope. On one side, it is pages. Double-sided, it is half of pages rounded up with first_page, and half of pages rounded down, plus 1, with extra_page. At most 6, counting the sheet the address adds, which is not charged.

The price of the letter. It is charged to the balance at creation or, for a scheduled letter, on its send date (on the account’s plan that day). It goes back to the balance if the letter is canceled after being charged or fails in production.

The scheduled send date, YYYY-MM-DD. null when the letter was sent right away.

Why the letter was canceled. null when it is not canceled.

Possible values

• requested: You canceled it, through the API or the dashboard.
• insufficient_balance: It was a scheduled letter and, on the send date, the balance did not cover the price. Nothing was charged.

Why the letter failed in production. null when it is not failed. When a letter fails, the amount goes back to the balance automatically.

Possible values

• unprintable_document: The file passed validation but could not be printed as it is.
• damaged_in_production: The letter was damaged in printing, folding or enveloping and could not be produced again.
• refused_by_carrier: Correios refused the letter at posting.
• other: Another reason. Contact CartaFlow support from the dashboard for the details.

The Correios tracking code of a registered letter (postal_services with registered), such as RA123456785BR. Filled in when the letter is posted. null for a simple letter, which has no tracking, and before posting.

Link to the final PDF, exactly as it will be printed, address included. The link works for 60 minutes: retrieve the letter again for a fresh link. The file stays available for at least 90 days after creation (or after the send date, for a scheduled letter); null only after that, if the file is no longer available. For a black-and-white letter the PDF keeps the original colors: the conversion to grayscale happens at printing.

Your identifier for this letter, such as the invoice number or the customer id in your system. Shown in the dashboard and usable as a filter when listing. It does not have to be unique. Up to 100 characters. null when you did not send one.

Key-value pairs to store your own data with the object, such as your customer or contract id. Returned in every response and webhook and never printed. Up to 20 keys; keys up to 40 characters and string values up to 500 characters. Do not store sensitive data such as passwords or card numbers. Empty object {} when you did not send any.

When the letter reached each status. null for statuses it has not reached. A scheduled letter starts as scheduled, at created_at.

When the letter was created and received, in UTC.