Referência da API

E-mail

Envie e-mails com Idempotency-Key obrigatória, liste os envios do ambiente da sua chave e acompanhe o status de cada um: entregue, bounce ou reclamação.

3 operações
URL basehttps://api.messages.ccxcompany.co
AutenticaçãoBearer com a sua chave de API

O texto técnico abaixo vem do contrato público, o openapi.json, no idioma em que o contrato foi escrito.

Lista os emails enviados

GET/v2/email/messages

Devolve os emails do AMBIENTE da credencial: uma chave ccx_test_* nunca vê envio de produção, e vice-versa.

O corpo do email não está aqui e não estará: guardamos bodyBytes, não o conteúdo.

Parâmetros

Campo	Onde	Tipo	Descrição
`status`opcional	query	`string`	Valores:`queuedsentdeliveredbouncedcomplainedfailed`
`to`opcional	query	`string`
`campaignId`opcional	query	`string`
`limit`opcional	query	`integer`
`skip`opcional	query	`integer`

Respostas

200Default Response

Campos e exemplo da resposta

Campo	Tipo	Descrição
`items`obrigatório	`object[]`
`items[].id`obrigatório	`string`
`items[].organizationId`obrigatório	`string`
`items[].env`opcional	`string`	Valores:`livetest`Padrão:`live`
`items[].to`obrigatório	`string · email`
`items[].from`obrigatório	`string`
`items[].subject`obrigatório	`string`
`items[].bodyBytes`obrigatório	`integer`
`items[].status`obrigatório	`string`	Valores:`queuedsentdeliveredbouncedcomplainedfailed`
`items[].reason`opcional	`string`	Valores:`invalid_addressmailbox_fullsuppressedcontent_rejectedcomplaintprovider_errorno_verified_sender`
`items[].contactId`opcional	`string`
`items[].campaignId`opcional	`string`
`items[].metadata`opcional	`object`	Metadados de correlação do seu sistema (ex.: customerId, journeyId), devolvidos intactos em todo webhook desta mensagem. Até 20 chaves; chave começa por letra e usa [A-Za-z0-9_.-] (até 64); valor é texto (até 256), número ou booleano. Não envie dado pessoal aqui.
`items[].sentAt`opcional	`string · date-time`
`items[].deliveredAt`opcional	`string · date-time`
`items[].failedAt`opcional	`string · date-time`
`items[].createdAt`obrigatório	`string · date-time`
`items[].updatedAt`obrigatório	`string · date-time`
`total`obrigatório	`integer`

JSON

{  "items": [    {      "id": "string",      "organizationId": "string",      "env": "live",      "to": "user@example.com",      "from": "string",      "subject": "string",      "bodyBytes": 0,      "status": "queued",      "reason": "invalid_address",      "contactId": "string",      "campaignId": "string",      "metadata": {},      "sentAt": "2026-10-16T12:00:00.000Z",      "deliveredAt": "2026-10-16T12:00:00.000Z",      "failedAt": "2026-10-16T12:00:00.000Z",      "createdAt": "2026-10-16T12:00:00.000Z",      "updatedAt": "2026-10-16T12:00:00.000Z"    }  ],  "total": 0}

400RFC 7807 problem details for BAD_REQUEST (400).
401RFC 7807 problem details for UNAUTHORIZED (401).
403RFC 7807 problem details for FORBIDDEN (403).

As respostas de erro seguem o formato RFC 7807 (application/problem+json), com um código estável no campo code. Ver os códigos de erro

Exemplo em curl

cURL

curl 'https://api.messages.ccxcompany.co/v2/email/messages' \  -H "Authorization: Bearer $CCX_API_KEY"

Só os campos obrigatórios. Troque os valores de exemplo pelos seus.

Envia um email

POST/v2/email/messages

Envio síncrono: a resposta chega depois de o provedor aceitar (ou recusar) a mensagem. Aceite não é entrega — entrega, bounce e reclamação são assíncronos e chegam no seu webhook.

`Idempotency-Key` é obrigatória. Sem ela o envio para com 400. Não derivamos uma do corpo: dois emails idênticos de propósito não podem virar um.

Ambiente: vem da credencial. Uma chave ccx_test_* cai no sandbox, e env: "test" sai carimbado na resposta. Não há como pedir um ambiente pelo corpo do request.

O sandbox mente em exatamente duas coisas, e a lista é fechada:

Nada chega em caixa de entrada nenhuma.
O envio de sandbox não conta no seu volume mensal. O preço em billing.coins é o real — mas um envio de teste nunca desloca o seu TIER.

Fora dessas duas, o sandbox é o produto: cobra de verdade (na carteira de sandbox), mesmo status, mesma latência.

Destinatários mágicos (sandbox): são os endereços do mailbox simulator que a própria SES opera — não uma tabela nossa. Em produção eles produzem exatamente os mesmos desfechos.

`to`	desfecho
`success@simulator.amazonses.com`	aceito; entrega
`bounce@simulator.amazonses.com`	aceito; bounce assíncrono
`complaint@simulator.amazonses.com`	aceito; reclamação assíncrona
`ooto@simulator.amazonses.com`	aceito; resposta automática de ausência
`suppressionlist@simulator.amazonses.com`	recusa síncrona — endereço na lista de supressão da conta
qualquer outro	aceito; entrega

Repare que só suppressionlist falha no POST. Bounce e reclamação são decisão do provedor e chegam DEPOIS — tratá-los no catch é o erro nº1 de quem integra com email.

Preço: billing.coins é o custo do envio, em coins (1 coin = R$ 0,0001). O email não tem faixa de volume (Cl. 8.8): é preço fixo por destinatário. Saldo insuficiente é 402.

Corpo: informe html, text, ou os dois. O corpo não é armazenado — guardamos bodyBytes, e não o conteúdo.

Ou envie por template. Com templateId, o assunto e o corpo vêm do template salvo — inclusive os escritos em MJML, que já ficam compilados. Preencha as {{variáveis}} com variables:

{ "to": "cliente@exemplo.com", "templateId": "etpl_…", "variables": { "nome": "Marina", "empresa": "Padaria Silva" } }

Com templateId, subject é opcional — informá-lo sobrescreve o do template (útil para A/B). Variável declarada no template e não informada aqui cai no example dele; sem exemplo, o placeholder sai vazio (nunca chega {{nome}} cru na caixa de entrada).

Opt-out: destinatário cujo contato pediu para não receber comunicação é recusado com 422 e meta.motivo: "opt_out". Para e-mail transacional (senha, pedido), envie transactional: true.

Permissão: email:send.

Corpo da requisição`application/json`

Campo	Tipo	Descrição
`to`obrigatório	`string · email`
`subject`opcional	`string`
`templateId`opcional	`string`
`variables`opcional	`object`
`html`opcional	`string`	Corpo HTML. Obrigatório informar `html` OU `text` (pelo menos um).
`text`opcional	`string`	Corpo texto puro. Obrigatório informar `html` OU `text` (pelo menos um).
`from`opcional	`string`
`contactId`opcional	`string`
`campaignId`opcional	`string`
`metadata`opcional	`object`	Metadados de correlação do seu sistema (ex.: customerId, journeyId), devolvidos intactos em todo webhook desta mensagem. Até 20 chaves; chave começa por letra e usa [A-Za-z0-9_.-] (até 64); valor é texto (até 256), número ou booleano. Não envie dado pessoal aqui.
`transactional`opcional	`boolean`	true para e-mail transacional (senha, pedido): sai mesmo para quem fez opt-out. Ausente ⇒ comunicação, bloqueada para quem saiu.

Exemplo completo do corpo

JSON

{  "to": "user@example.com",  "subject": "string",  "templateId": "string",  "variables": {},  "html": "string",  "text": "string",  "from": "string",  "contactId": "string",  "campaignId": "string",  "metadata": {},  "transactional": true}

Respostas

201Default Response

Campos e exemplo da resposta

Campo	Tipo	Descrição
`id`obrigatório	`string`
`status`obrigatório	`string`	Valores:`queuedsentdeliveredbouncedcomplainedfailed`
`env`obrigatório	`string`	Valores:`livetest`
`to`obrigatório	`string`
`from`obrigatório	`string`
`subject`obrigatório	`string`
`bodyBytes`obrigatório	`integer`
`replayed`obrigatório	`boolean`
`billing`opcional	`object`
`billing.coins`obrigatório	`integer`
`contactId`opcional	`string`
`campaignId`opcional	`string`
`metadata`opcional	`object`	Metadados de correlação do seu sistema (ex.: customerId, journeyId), devolvidos intactos em todo webhook desta mensagem. Até 20 chaves; chave começa por letra e usa [A-Za-z0-9_.-] (até 64); valor é texto (até 256), número ou booleano. Não envie dado pessoal aqui.
`createdAt`obrigatório	`string · date-time`
`sentAt`opcional	`string · date-time`

JSON

{  "id": "string",  "status": "queued",  "env": "live",  "to": "string",  "from": "string",  "subject": "string",  "bodyBytes": 0,  "replayed": true,  "billing": {    "coins": 0  },  "contactId": "string",  "campaignId": "string",  "metadata": {},  "createdAt": "2026-10-16T12:00:00.000Z",  "sentAt": "2026-10-16T12:00:00.000Z"}

400RFC 7807 problem details for BAD_REQUEST (400).
401RFC 7807 problem details for UNAUTHORIZED (401).
402RFC 7807 problem details for PAYMENT_REQUIRED (402).
403RFC 7807 problem details for FORBIDDEN (403).
412RFC 7807 problem details for PRECONDITION_FAILED (412).
422RFC 7807 problem details for VALIDATION_ERROR (422).
502RFC 7807 problem details for DEPENDENCY_FAILED (502).

As respostas de erro seguem o formato RFC 7807 (application/problem+json), com um código estável no campo code. Ver os códigos de erro

Exemplo em curl

cURL

curl -X POST 'https://api.messages.ccxcompany.co/v2/email/messages' \  -H "Authorization: Bearer $CCX_API_KEY" \  -H "Idempotency-Key: order-4821" \  -H "Content-Type: application/json" \  -d '{    "to": "user@example.com"  }'

Só os campos obrigatórios. Troque os valores de exemplo pelos seus.

Lê um email pelo id

GET/v2/email/messages/{id}

O status conta a história do envio: queued → sent (o provedor aceitou) → delivered | bounced | complained. failed é recusa antes de sair.

404 também é a resposta para um email de outro ambiente ou de outra organização — distinguir “não existe” de “não é seu” contaria a existência de dado alheio.

Parâmetros

Campo	Onde	Tipo	Descrição
`id`obrigatório	caminho	`string`

Respostas

200Default Response

Campos e exemplo da resposta

Campo	Tipo	Descrição
`id`obrigatório	`string`
`organizationId`obrigatório	`string`
`env`opcional	`string`	Valores:`livetest`Padrão:`live`
`to`obrigatório	`string · email`
`from`obrigatório	`string`
`subject`obrigatório	`string`
`bodyBytes`obrigatório	`integer`
`status`obrigatório	`string`	Valores:`queuedsentdeliveredbouncedcomplainedfailed`
`reason`opcional	`string`	Valores:`invalid_addressmailbox_fullsuppressedcontent_rejectedcomplaintprovider_errorno_verified_sender`
`contactId`opcional	`string`
`campaignId`opcional	`string`
`metadata`opcional	`object`	Metadados de correlação do seu sistema (ex.: customerId, journeyId), devolvidos intactos em todo webhook desta mensagem. Até 20 chaves; chave começa por letra e usa [A-Za-z0-9_.-] (até 64); valor é texto (até 256), número ou booleano. Não envie dado pessoal aqui.
`sentAt`opcional	`string · date-time`
`deliveredAt`opcional	`string · date-time`
`failedAt`opcional	`string · date-time`
`createdAt`obrigatório	`string · date-time`
`updatedAt`obrigatório	`string · date-time`

JSON

{  "id": "string",  "organizationId": "string",  "env": "live",  "to": "user@example.com",  "from": "string",  "subject": "string",  "bodyBytes": 0,  "status": "queued",  "reason": "invalid_address",  "contactId": "string",  "campaignId": "string",  "metadata": {},  "sentAt": "2026-10-16T12:00:00.000Z",  "deliveredAt": "2026-10-16T12:00:00.000Z",  "failedAt": "2026-10-16T12:00:00.000Z",  "createdAt": "2026-10-16T12:00:00.000Z",  "updatedAt": "2026-10-16T12:00:00.000Z"}

400RFC 7807 problem details for BAD_REQUEST (400).
401RFC 7807 problem details for UNAUTHORIZED (401).
403RFC 7807 problem details for FORBIDDEN (403).
404RFC 7807 problem details for NOT_FOUND (404).

As respostas de erro seguem o formato RFC 7807 (application/problem+json), com um código estável no campo code. Ver os códigos de erro

Exemplo em curl

cURL

curl 'https://api.messages.ccxcompany.co/v2/email/messages/<id>' \  -H "Authorization: Bearer $CCX_API_KEY"

Só os campos obrigatórios. Troque os valores de exemplo pelos seus.

Travou em alguma rota? Fale com quem mantém a API.

Criar conta grátis Falar com vendas

Criando a conta pelo site, você ganha R$ 10 de crédito de teste.

E-mail

Lista os emails enviados

Parâmetros

Respostas

Exemplo em curl

Envia um email

Corpo da requisiçãoapplication/json

Respostas

Exemplo em curl

Lê um email pelo id

Parâmetros

Respostas

Exemplo em curl

Outras áreas da API

Travou em alguma rota? Fale com quem mantém a API.

Corpo da requisição`application/json`