API, cartas em série e envio por e-mail

Envie cartas diretamente a partir do seu software – através da API REST, como carta em série ou simplesmente por e-mail. O conector do Claude utiliza as mesmas funções.

Autenticação

Crie uma chave em Conta → Chaves de API e envie-a como bearer token. Cada pedido debita apenas o saldo dessa conta.

curl -H "Authorization: Bearer mbx_…" https://mcpbrief.de/api/v1/balance

Descrição OpenAPI: https://mcpbrief.de/openapi.json

Endpoints

GET	/balance	Saldo, preços, remetente, limite diário
POST	/letter/price	Verificar endereço, montar carta, páginas e preço + pré-visualização em PDF (não envia nada)
POST	/letter/send	Enviar uma carta (texto, PDF, DOCX, imagem; anexos, duplex, centro de custo)
GET	/letter/{id}	Estado e número de seguimento
POST	/letter/{id}/cancel	Cancelar antes da impressão (reembolso)
POST	/letter/{id}/resend	Enviar novamente
GET	/letters?limit=&status=&since=&cost_center=&batch_id=	Lista das suas cartas, com filtros
POST	/letters/batch/price	Verificar uma carta em série: todos os endereços, marcadores, preço total
POST	/letters/batch/send	Enviar uma carta em série (máx. 200 destinatários)

Exemplo: correio registado com anexo

curl -X POST https://mcpbrief.de/api/v1/letter/send \
  -H "Authorization: Bearer mbx_…" -H "Content-Type: application/json" \
  -d '{
  "recipient": {"name": "Muster GmbH", "street": "Ringstraße 5",
                "zip": "1010", "city": "Wien", "country": "AT"},
  "subject": "Rechnung 2026-17",
  "content": "Sehr geehrte Damen und Herren,\n\nanbei …",
  "attachments": [{"file_base64": "JVBERi0…", "file_name": "rechnung.pdf"}],
  "delivery": "registered", "duplex": true, "cost_center": "VERTRIEB",
  "idempotency_key": "7d1c2f0e-…"
}'

Exemplo: carta em série

curl -X POST https://mcpbrief.de/api/v1/letters/batch/send \
  -H "Authorization: Bearer mbx_…" -H "Content-Type: application/json" \
  -d '{
  "recipients": [
    {"name": "Muster GmbH", "street": "Ringstraße 5", "zip": "1010",
     "city": "Wien", "country": "AT", "anrede": "Sehr geehrte Frau Huber"},
    {"name": "Beispiel AG", "street": "Hauptstraße 1", "zip": "10115",
     "city": "Berlin", "country": "DE", "anrede": "Sehr geehrte Damen und Herren"}
  ],
  "subject": "Preisanpassung 2027",
  "content": "{{anrede}},\n\nab 1. Jänner gelten neue Preise …",
  "delivery": "standard", "idempotency_key": "batch-2027-01"
}'

Cartas por e-mail

Sem programação: cada conta tem um endereço de encomenda pessoal. Os PDFs que enviar a partir do e-mail da sua conta para este endereço são expedidos como cartas.

Cada PDF em anexo = uma carta, endereço na zona da janela (DIN 5008)
O assunto controla as opções: Registado, Prioritário, Cores, Duplex, Ref: …, País: …
“Anexo” no assunto: todos os ficheiros são combinados numa só carta
“Teste” no assunto: apenas verificação e preço por e-mail – nada é enviado

Valores de estado

O endpoint de estado, a lista e a notificação por e-mail mostram o estado atual.

`pending`	em fila de espera
`processing`	em impressão e envelopagem
`mailed`	entregue aos correios
`failed`	não enviada
`cancelled`	cancelada
`undeliverable`	não entregável
`rejected`	rejeitada