Agendar envios

Com o campo send_date, você cria a correspondência agora e escolhe a data em que ela entra em produção. Serve para lembretes de consulta, renovações, aniversários e qualquer envio que já tem data marcada.

Como funcionaCopiar link da seção

Agendar uma correspondênciaCopiar link da seção

Envie o mesmo corpo de Criar uma correspondência, com send_date no formato AAAA-MM-DD. Vale para as duas formas de envio: em JSON, como abaixo, ou com o PDF como arquivo em multipart/form-data, com send_date como mais uma parte do formulário. Veja Documento e área do endereço.

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

A resposta é uma correspondência com status: scheduled, send_date: "2026-10-20" e received_at: null. O campo price já mostra o preço calculado no plano de hoje.

Regras de send_dateCopiar link da seção

• Formato AAAA-MM-DD, só a data. O horário não é escolhido: a cobrança acontece às 06:00 de Brasília (fuso America/Sao_Paulo) no dia marcado.
• A data vai de amanhã até 180 dias à frente. Uma data fora desse intervalo recebe 422, com o problema apontado em send_date.
• Para enviar na hora, não envie o campo. Não existe agendamento para hoje.
• A data não muda depois da criação. Para escolher outro dia, cancele e crie de novo.

O que a CartaFlow confere na criação e na dataCopiar link da seção

Cancelar uma correspondência agendadaCopiar link da seção

Enquanto ela estiver em scheduled, cancele com POST /v1/letters/{letter_id}/cancel. Nada foi cobrado, então não há devolução. A correspondência passa para canceled com cancellation_reason: requested. Veja Correspondências e status.

Alterar uma correspondência agendadaCopiar link da seção

Pela API, uma correspondência não muda depois de criada: para mudar algo, cancele (sem custo enquanto ela estiver agendada) e crie outra. No painel, em Envios, uma correspondência agendada pode mudar de data, de endereço, de arquivo, de variáveis, de impressão, de serviços dos Correios e de referência, sem custo, ou ser enviada na hora, quando é cobrada. Veja Correspondências e status.

EventosCopiar link da seção

Uma correspondência agendada gera estes eventos, em ordem:

1. letter.scheduled na criação.
2. letter.updated sempre que ela for alterada no painel antes da data, com a correspondência como ficou (a nova send_date, por exemplo).
3. letter.received na data do envio, depois da cobrança, ou na hora em que ela for enviada pelo painel. Ou letter.canceled com cancellation_reason: insufficient_balance, se o saldo não cobriu o preço na data.
4. letter.in_production, letter.printed e letter.posted, como em qualquer correspondência.

Boas práticasCopiar link da seção

• Mantenha o saldo em dia. Antes de uma data com muitos envios, some os preços das correspondências agendadas e confira o saldo com GET /v1/balance.
• Ouça letter.canceled. Quando o motivo for insufficient_balance, avise a sua equipe ou recarregue o saldo e crie a correspondência de novo.
• Liste o que está agendado com GET /v1/letters?status=scheduled. Combine com created_after e created_before para ver um período.