API reference
Webhooks
Endpoints that receive events, deliveries, replay and secret rotation.
List webhooks
GET
https://api.coffeemail.com.br/v1/product/webhooks200Query parameters
statusstring- Filtra webhooks pelo status (active, paused ou disabled)
Response 200
webhooksarray<object>required- Lista de webhooks cadastrados na organização
Create webhook
POST
https://api.coffeemail.com.br/v1/product/webhooks201Request body
urlstring (uri)required- URL de destino que receberá os eventos
eventsarray<"email.queued" | "email.processing" | "email.sent" | "email.delivered" | "email.delivery_delayed" | "email.opened" | "email.clicked" | "email.bounced" | "email.complained" | "email.failed" | "email.suppressed" | "email.scheduled" | "email.cancelled" | "email.unsubscribed" | "billing.plan_changed">1+ itensrequired- Eventos aos quais o webhook deve se inscrever
descriptionstring≤ 500- Descrição opcional do webhook
Response 201
idstring (uuid)required- Identificador do webhook
urlstringrequired- URL de destino que recebe os eventos
eventsarray<"email.queued" | "email.processing" | "email.sent" | "email.delivered" | "email.delivery_delayed" | "email.opened" | "email.clicked" | "email.bounced" | "email.complained" | "email.failed" | "email.suppressed" | "email.scheduled" | "email.cancelled" | "email.unsubscribed" | "billing.plan_changed">required- Eventos aos quais o webhook está inscrito
status"active" | "paused" | "disabled"required- Status atual do webhook (active, paused ou disabled)
descriptionstringrequired- Descrição informada pelo usuário para o webhook
createdAtstring (date-time)required- Data e hora de criação do webhook
secretstring≥ 1required- Segredo usado para assinar os payloads enviados, exibido uma única vez
Get webhook
GET
https://api.coffeemail.com.br/v1/product/webhooks/{id}200Path parameters
idstringrequired- Identificador do webhook
Response 200
idstring (uuid)required- Identificador do webhook
urlstringrequired- URL de destino que recebe os eventos
eventsarray<"email.queued" | "email.processing" | "email.sent" | "email.delivered" | "email.delivery_delayed" | "email.opened" | "email.clicked" | "email.bounced" | "email.complained" | "email.failed" | "email.suppressed" | "email.scheduled" | "email.cancelled" | "email.unsubscribed" | "billing.plan_changed">required- Eventos aos quais o webhook está inscrito
status"active" | "paused" | "disabled"required- Status atual do webhook (active, paused ou disabled)
descriptionstringrequired- Descrição informada pelo usuário para o webhook
createdAtstring (date-time)required- Data e hora de criação do webhook
metrics7dobject- Saúde das entregas do webhook nos últimos 7 dias
metrics7d.deliveredintegermín. 0máx. 9007199254740991required- Entregas com sucesso nos últimos 7 dias
metrics7d.failedintegermín. 0máx. 9007199254740991required- Entregas que falharam de vez (failed ou exhausted) nos últimos 7 dias
metrics7d.successRatenumbermín. 0máx. 100required- Sucesso ÷ (sucesso + falha), em %; null sem entregas concluídas
metrics7d.p95Msintegermín. 0máx. 9007199254740991required- Percentil 95 da duração das tentativas, em ms; null sem medição
metrics7d.lastDeliveryAtstring (date-time)required- Última tentativa de entrega no período
metrics7d.lastStatusintegermín. -9007199254740991máx. 9007199254740991required- Status HTTP da última tentativa que recebeu resposta
retryPolicyobject- Política de repetição aplicada às entregas
retryPolicy.maxAttemptsintegermín. 0máx. 9007199254740991required- Tentativas antes de desistir da entrega
retryPolicy.backoffBaseMsintegermín. 0máx. 9007199254740991required- Espera da primeira repetição, em ms
retryPolicy.backoffMaxMsintegermín. 0máx. 9007199254740991required- Espera máxima entre repetições, em ms
secretstringrequired- Segredo de assinatura completo (quando disponível)
secretPreviewstringrequired- Prévia truncada do segredo, para exibição segura
Update webhook
PUT
https://api.coffeemail.com.br/v1/product/webhooks/{id}200Path parameters
idstringrequired- Identificador do webhook
Request body
urlstring (uri)- Nova URL de destino que receberá os eventos
eventsarray<"email.queued" | "email.processing" | "email.sent" | "email.delivered" | "email.delivery_delayed" | "email.opened" | "email.clicked" | "email.bounced" | "email.complained" | "email.failed" | "email.suppressed" | "email.scheduled" | "email.cancelled" | "email.unsubscribed" | "billing.plan_changed">1+ itens- Novos eventos aos quais o webhook deve se inscrever
descriptionstring≤ 500- Nova descrição do webhook
Response 200
idstring (uuid)required- Identificador do webhook
urlstringrequired- URL de destino que recebe os eventos
eventsarray<"email.queued" | "email.processing" | "email.sent" | "email.delivered" | "email.delivery_delayed" | "email.opened" | "email.clicked" | "email.bounced" | "email.complained" | "email.failed" | "email.suppressed" | "email.scheduled" | "email.cancelled" | "email.unsubscribed" | "billing.plan_changed">required- Eventos aos quais o webhook está inscrito
status"active" | "paused" | "disabled"required- Status atual do webhook (active, paused ou disabled)
descriptionstringrequired- Descrição informada pelo usuário para o webhook
createdAtstring (date-time)required- Data e hora de criação do webhook
metrics7dobject- Saúde das entregas do webhook nos últimos 7 dias
metrics7d.deliveredintegermín. 0máx. 9007199254740991required- Entregas com sucesso nos últimos 7 dias
metrics7d.failedintegermín. 0máx. 9007199254740991required- Entregas que falharam de vez (failed ou exhausted) nos últimos 7 dias
metrics7d.successRatenumbermín. 0máx. 100required- Sucesso ÷ (sucesso + falha), em %; null sem entregas concluídas
metrics7d.p95Msintegermín. 0máx. 9007199254740991required- Percentil 95 da duração das tentativas, em ms; null sem medição
metrics7d.lastDeliveryAtstring (date-time)required- Última tentativa de entrega no período
metrics7d.lastStatusintegermín. -9007199254740991máx. 9007199254740991required- Status HTTP da última tentativa que recebeu resposta
retryPolicyobject- Política de repetição aplicada às entregas
retryPolicy.maxAttemptsintegermín. 0máx. 9007199254740991required- Tentativas antes de desistir da entrega
retryPolicy.backoffBaseMsintegermín. 0máx. 9007199254740991required- Espera da primeira repetição, em ms
retryPolicy.backoffMaxMsintegermín. 0máx. 9007199254740991required- Espera máxima entre repetições, em ms
secretstringrequired- Segredo de assinatura completo (quando disponível)
secretPreviewstringrequired- Prévia truncada do segredo, para exibição segura
Pause or resume webhook
PATCH
https://api.coffeemail.com.br/v1/product/webhooks/{id}200Path parameters
idstringrequired- Identificador do webhook
Request body
status"active" | "paused"required- Novo status do webhook (ativo ou pausado)
Delete webhook
DELETE
https://api.coffeemail.com.br/v1/product/webhooks/{id}200Path parameters
idstringrequired- Identificador do webhook
Send a test event
POST
https://api.coffeemail.com.br/v1/product/webhooks/{id}/test200Path parameters
idstringrequired- Identificador do webhook
Response 200
status"success" | "failed"required- Resultado do envio de teste
statusCodeintegermín. -9007199254740991máx. 9007199254740991required- Status HTTP retornado pelo endpoint de destino
latencyMsintegermín. 0máx. 9007199254740991required- Tempo total do disparo de teste, em milissegundos
bodystringrequired- Primeiro 1 KB do corpo da resposta retornada pelo endpoint de destino
errorstringrequired- Mensagem de erro, caso o envio de teste tenha falhado
List deliveries
GET
https://api.coffeemail.com.br/v1/product/webhooks/{id}/deliveries200Path parameters
idstringrequired- Identificador do webhook
Query parameters
eventTypestring- Filtra entregas por tipo de evento
status"pending" | "success" | "failed" | "exhausted"- Filtra entregas pelo status atual
fromstring (date-time)- Data inicial do período de busca
tostring (date-time)- Data final do período de busca
limitintegermín. 0máx. 200- Quantidade máxima de entregas retornadas
pageintegermín. 0máx. 100000- Página numerada (começa em 1). Ignorada quando `after` é enviado
afterstring≥ 1≤ 512- Cursor opaco de paginação: envie o nextCursor da página anterior para receber as entregas mais antigas que ela. Cursor inválido ou adulterado retorna 400
Response 200
deliveriesarray<object>required- Lista de tentativas de entrega do webhook, da mais recente para a mais antiga
nextCursorstringrequired- Cursor da próxima página (use em after); null quando não há mais entregas
paginationobject- Paginação numerada. Ausente quando a consulta usa cursor (`after`)
pagination.totalintegermín. 0máx. 9007199254740991required- Total de itens que batem com os filtros
pagination.pageintegermín. 0máx. 9007199254740991required- Página atual (começa em 1)
pagination.limitintegermín. 0máx. 9007199254740991required- Itens por página
pagination.totalPagesintegermín. 0máx. 9007199254740991required- Quantidade de páginas
pagination.totalIsEstimatebooleanrequired- true quando o total passa de 10000 e vem de estimativa
Deliveries of an email
GET
https://api.coffeemail.com.br/v1/product/emails/{id}/webhook-deliveries200Path parameters
idstring (uuid)required- Identificador do e-mail
Response 200
deliveriesarray<object>required- Entregas de webhook disparadas por este e-mail, da mais recente para a mais antiga
Get delivery
GET
https://api.coffeemail.com.br/v1/product/webhooks/{id}/deliveries/{deliveryId}200Path parameters
idstringrequired- Identificador do webhook
deliveryIdstring (uuid)required- Identificador da entrega
Response 200
idstring (uuid)required- Identificador da tentativa de entrega
webhookIdstring (uuid)required- Identificador do webhook associado
emailEventIdstring (uuid)required- Evento de e-mail que originou a entrega
eventTypestringrequired- Tipo de evento disparado (ex: email.delivered)
responseStatusintegermín. -9007199254740991máx. 9007199254740991required- Status HTTP retornado pelo endpoint de destino
responseBodystringrequired- Corpo da resposta retornada pelo endpoint de destino
attemptsintegermín. -9007199254740991máx. 9007199254740991required- Quantidade de tentativas de envio já realizadas
durationMsintegermín. 0máx. 9007199254740991- Duração da última tentativa, em ms; null para entregas antigas
lastErrorstringrequired- Mensagem do último erro ocorrido no envio
statusstringrequired- Status atual da entrega (pending, success, failed ou exhausted)
nextRunAtstring (date-time)required- Data e hora da próxima tentativa de reenvio
createdAtstring (date-time)required- Data e hora em que a entrega foi criada
requestPayloadstringrequired- Corpo JSON enviado ao endpoint de destino
Replay delivery
POST
https://api.coffeemail.com.br/v1/product/webhooks/{id}/deliveries/{deliveryId}/replay202Path parameters
idstringrequired- Identificador do webhook
deliveryIdstring (uuid)required- Identificador da entrega
Response 202
idstring (uuid)required- Identificador da tentativa de entrega
webhookIdstring (uuid)required- Identificador do webhook associado
emailEventIdstring (uuid)required- Evento de e-mail que originou a entrega
eventTypestringrequired- Tipo de evento disparado (ex: email.delivered)
responseStatusintegermín. -9007199254740991máx. 9007199254740991required- Status HTTP retornado pelo endpoint de destino
responseBodystringrequired- Corpo da resposta retornada pelo endpoint de destino
attemptsintegermín. -9007199254740991máx. 9007199254740991required- Quantidade de tentativas de envio já realizadas
durationMsintegermín. 0máx. 9007199254740991- Duração da última tentativa, em ms; null para entregas antigas
lastErrorstringrequired- Mensagem do último erro ocorrido no envio
statusstringrequired- Status atual da entrega (pending, success, failed ou exhausted)
nextRunAtstring (date-time)required- Data e hora da próxima tentativa de reenvio
createdAtstring (date-time)required- Data e hora em que a entrega foi criada
requestPayloadstringrequired- Corpo JSON enviado ao endpoint de destino
Rotate secret
POST
https://api.coffeemail.com.br/v1/product/webhooks/{id}/rotate-secret200Path parameters
idstringrequired- Identificador do webhook