Referencia de la API

Email

Envía emails con Idempotency-Key obligatoria, lista los envíos del entorno de tu clave y sigue el estado de cada uno: entregado, rebotado o con queja.

3 operaciones
URL basehttps://api.messages.ccxcompany.co
AutenticaciónBearer con tu clave de API

El texto técnico de abajo viene del contrato público, openapi.json, en el idioma en que se escribió el contrato.

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	Dónde	Tipo	Descripción
`status`opcional	query	`string`	Valores:`queuedsentdeliveredbouncedcomplainedfailed`
`to`opcional	query	`string`
`campaignId`opcional	query	`string`
`limit`opcional	query	`integer`
`skip`opcional	query	`integer`

Respuestas

200Default Response

Campos y ejemplo de la respuesta

Campo	Tipo	Descripción
`items`obligatorio	`object[]`
`items[].id`obligatorio	`string`
`items[].organizationId`obligatorio	`string`
`items[].env`opcional	`string`	Valores:`livetest`Por defecto:`live`
`items[].to`obligatorio	`string · email`
`items[].from`obligatorio	`string`
`items[].subject`obligatorio	`string`
`items[].bodyBytes`obligatorio	`integer`
`items[].status`obligatorio	`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`obligatorio	`string · date-time`
`items[].updatedAt`obligatorio	`string · date-time`
`total`obligatorio	`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).

Las respuestas de error siguen el formato RFC 7807 (application/problem+json), con un código estable en el campo code. Ver los códigos de error

Ejemplo en curl

cURL

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

Solo los campos obligatorios. Cambia los valores de ejemplo por los tuyos.

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.

Cuerpo de la petición`application/json`

Campo	Tipo	Descripción
`to`obligatorio	`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.

Ejemplo completo del cuerpo

JSON

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

Respuestas

201Default Response

Campos y ejemplo de la respuesta

Campo	Tipo	Descripción
`id`obligatorio	`string`
`status`obligatorio	`string`	Valores:`queuedsentdeliveredbouncedcomplainedfailed`
`env`obligatorio	`string`	Valores:`livetest`
`to`obligatorio	`string`
`from`obligatorio	`string`
`subject`obligatorio	`string`
`bodyBytes`obligatorio	`integer`
`replayed`obligatorio	`boolean`
`billing`opcional	`object`
`billing.coins`obligatorio	`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`obligatorio	`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).

Las respuestas de error siguen el formato RFC 7807 (application/problem+json), con un código estable en el campo code. Ver los códigos de error

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

Solo los campos obligatorios. Cambia los valores de ejemplo por los tuyos.

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	Dónde	Tipo	Descripción
`id`obligatorio	ruta	`string`

Respuestas

200Default Response

Campos y ejemplo de la respuesta

Campo	Tipo	Descripción
`id`obligatorio	`string`
`organizationId`obligatorio	`string`
`env`opcional	`string`	Valores:`livetest`Por defecto:`live`
`to`obligatorio	`string · email`
`from`obligatorio	`string`
`subject`obligatorio	`string`
`bodyBytes`obligatorio	`integer`
`status`obligatorio	`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`obligatorio	`string · date-time`
`updatedAt`obligatorio	`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).

Las respuestas de error siguen el formato RFC 7807 (application/problem+json), con un código estable en el campo code. Ver los códigos de error

Ejemplo en curl

cURL

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

Solo los campos obligatorios. Cambia los valores de ejemplo por los tuyos.

¿Atascado en una ruta? Habla con quienes mantienen la API.

Empieza gratis Habla con ventas

Si creas la cuenta desde la web, recibes 5 US$ de crédito de prueba.

Email

Lista os emails enviados

Parámetros

Respuestas

Ejemplo en curl

Envia um email

Cuerpo de la peticiónapplication/json

Respuestas

Ejemplo en curl

Lê um email pelo id

Parámetros

Respuestas

Ejemplo en curl

Otras áreas de la API

¿Atascado en una ruta? Habla con quienes mantienen la API.

Cuerpo de la petición`application/json`