Brazil mail API for automated mailings
Your system sends a PDF and a Brazilian address. We print it, envelope it and post it through Correios.
New accounts get R$50 in credit, enough for 3 simple letters.
curl https://api.cartaflow.com.br/v1/letters \
-H "Authorization: Bearer $CARTAFLOW_API_KEY" \
-H "Idempotency-Key: fatura-2026-10-0042" \
-F "to[name]=Destinatário Exemplo" \
-F "to[address_line1]=Rua Exemplo, 128" \
-F "to[address_line2]=Ap. 52" \
-F "to[district]=Centro" \
-F "to[city]=São Paulo" \
-F "to[state]=SP" \
-F "to[cep]=01001-000" \
-F "color=true" \
-F "file=@fatura-outubro.pdf"import { readFile } from 'node:fs/promises';
const form = new FormData();
form.append('to[name]', 'Destinatário Exemplo');
form.append('to[address_line1]', 'Rua Exemplo, 128');
form.append('to[address_line2]', 'Ap. 52');
form.append('to[district]', 'Centro');
form.append('to[city]', 'São Paulo');
form.append('to[state]', 'SP');
form.append('to[cep]', '01001-000');
form.append('color', 'true');
form.append('file', new Blob([await readFile('fatura-outubro.pdf')]), 'fatura-outubro.pdf');
const res = await fetch('https://api.cartaflow.com.br/v1/letters', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.CARTAFLOW_API_KEY}`,
'Idempotency-Key': 'fatura-2026-10-0042',
},
body: form,
});
const letter = await res.json();import os
import requests
letter = requests.post(
"https://api.cartaflow.com.br/v1/letters",
headers={
"Authorization": f"Bearer {os.environ['CARTAFLOW_API_KEY']}",
"Idempotency-Key": "fatura-2026-10-0042",
},
data={
"to[name]": "Destinatário Exemplo",
"to[address_line1]": "Rua Exemplo, 128",
"to[address_line2]": "Ap. 52",
"to[district]": "Centro",
"to[city]": "São Paulo",
"to[state]": "SP",
"to[cep]": "01001-000",
"color": "true",
},
files={"file": open("fatura-outubro.pdf", "rb")},
).json()Illustrative API example, subject to change before launch.
What the API does
One request creates one physical mailing in Brazil. The rest of the work happens on our side.
A mailing from a PDF
Send the PDF and the recipient’s Brazilian address in one request. We print the file exactly as it is.
Color or black and white
Choose color printing for branded mail, or black and white for plain notices.
Safe retries
Send an Idempotency-Key header. If your system repeats the request, CartaFlow does not create a second mailing.
Status up to posting
Each mailing moves from received to printed to posted, or canceled. Postal tracking after posting is not offered.
Test keys
Build the integration with test keys. Test requests never print, post or bill anything.
Same price as the dashboard
Mailings created through the API use your plan and the same price per mailing.
Example: monthly invoices for customers in Brazil
For example, a software company abroad bills its Brazilian customers in reais and some of them need a printed invoice with a boleto.
- 1
The billing run creates the PDFs
Each invoice already includes the boleto, in Portuguese, with the company’s logo and colors.
- 2
The system calls the API once per invoice
With the PDF, the customer’s address and an idempotency key built from the invoice number.
- 3
CartaFlow prints and posts
Each invoice goes out in its own envelope, and the system reads the status as the mailing is printed and posted.
{
"id": "ltr_8Kq2wX4m",
"object": "letter",
"status": "received",
"pages": 2,
"to": {
"name": "Destinatário Exemplo",
"cep": "01001-000",
"city": "São Paulo",
"state": "SP"
},
"created_at": "2026-10-13T14:20:00Z"
}Illustrative API example, subject to change before launch. The response returns the new mailing with the status received.
View documentationMailing statuses
CartaFlow reports what happens while the mailing is with us. After posting, delivery follows Correios and is not tracked or guaranteed.
| Status | What it means |
|---|---|
received | CartaFlow received the file and the address, and the mailing is waiting to be printed. |
printed | The document was printed and put in its envelope. |
posted | The mailing was posted through Correios. This is the last status CartaFlow reports. |
canceled | The mailing was canceled before printing and will not be sent. |
Where the API fits
Any system that already produces documents for Brazilian recipients can send them as physical mail.
Billing systems
Invoices, boletos and payment reminders, sent after each billing run.
ERPs and CRMs
Contract changes and notices sent from the tool your team already uses.
Product events
An approved application or a delivered card can trigger a mailing.
Address checks
Mail a code to a new user’s address before you trust it.
API questions
Pricing questions are on the pricing page.
What does a request need?
A PDF and the recipient's name, street and number, district, city, two-letter state code and CEP (the Brazilian postal code). You can also choose color printing and add your own reference.
Can I send many mailings at once?
Create one request per mailing. Your system can send them one after another after a billing run, for example. If you prefer not to write code, the dashboard sends a batch.
Can I track the mailing after it is posted?
No. The API reports each mailing as received, printed and posted. Postal tracking after posting is not offered, and delivery time is not guaranteed.
What language should the PDF be in?
Your recipients are in Brazil, so most businesses send their mail in Portuguese. CartaFlow prints the PDF as sent and does not translate it.
Can I test without sending real mail?
Yes. Requests made with a test key go through the API like real ones, but nothing is printed, posted or billed.
Is there API documentation?
Yes, at docs.cartaflow.com.br, with the full API reference. The examples on this page show the shape of the calls and may change before launch.
Send your first letter free.
New accounts get R$50 in credit, enough for 3 simple letters.