Scheduling

With the send_date field you create a letter now and choose the date it goes into production. Use it for appointment reminders, renewals, birthdays and any mailing that already has a date.

How it worksCopy Anchor Link

Schedule a letterCopy Anchor Link

Send the same body as Create a letter, plus send_date formatted as YYYY-MM-DD. Both request formats work: JSON, as below, or the PDF uploaded as a file in multipart/form-data, with send_date as one more form part. See Document and address area.

curl -X POST "https://api.cartaflow.com.br/v1/letters" \
  -H "Authorization: Bearer $CARTAFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: lembrete-revisao-2291" \
  -d '{
    "to": {
      "name": "Destinatário Exemplo",
      "postal_code": "01001-000",
      "number": "128",
      "complement": "Ap. 52"
    },
    "document": {
      "type": "url",
      "url": "https://arquivos.exemplo.com.br/lembretes/revisao-2291.pdf"
    },
    "send_date": "2026-10-20",
    "reference": "lembrete-revisao-2291"
  }'

The response is a letter with status: scheduled, send_date: "2026-10-20" and received_at: null. The price field already shows the price on today’s plan.

send_date rulesCopy Anchor Link

• Format YYYY-MM-DD, date only. You do not pick a time: the charge happens at 06:00 Brasília time (time zone America/Sao_Paulo) on that day.
• The date can be from tomorrow up to 180 days ahead. A date outside that range gets a 422, with the problem pointed at send_date.
• To send right away, leave the field out. There is no scheduling for today.
• The date cannot change after creation. To pick another day, cancel and create the letter again.

What CartaFlow checks at creation and on the dateCopy Anchor Link

Cancel a scheduled letterCopy Anchor Link

While the letter is scheduled, cancel it with POST /v1/letters/{letter_id}/cancel. Nothing was charged, so there is no refund. The letter moves to canceled with cancellation_reason: requested. See Letters and statuses.

Change a scheduled letterCopy Anchor Link

Through the API, a letter does not change after it is created: to change something, cancel it (free while it is scheduled) and create another. In the dashboard, under Envios (Letters), a scheduled letter can change its date, address, file, variables, printing, Correios services and reference at no cost, or be sent right away, which charges it. See Letters and statuses.

EventsCopy Anchor Link

A scheduled letter produces these events, in order:

1. letter.scheduled at creation.
2. letter.updated every time it is changed in the dashboard before its date, with the letter as it is now (the new send_date, for example).
3. letter.received on the send date, after the charge, or when it is sent right away from the dashboard. Or letter.canceled with cancellation_reason: insufficient_balance, if the balance did not cover the price on the date.
4. letter.in_production, letter.printed and letter.posted, as for any letter.

Good practiceCopy Anchor Link

• Keep the balance topped up. Before a date with many mailings, add up the prices of the scheduled letters and check the balance with GET /v1/balance.
• Listen to letter.canceled. When the reason is insufficient_balance, alert your team, or top up the balance and create the letter again.
• List what is scheduled with GET /v1/letters?status=scheduled. Combine it with created_after and created_before to see a period.