API de e-mail transacional
Envie e-mails transacionais com a chave de API do workspace, acompanhe cada envio e trate as recusas.
A API de e-mail transacional envia e-mails como redefinição de senha, recibos, códigos de acesso e avisos pelo domínio verificado do workspace, e registra o que aconteceu com cada um. É a única parte da API que aceita a chave de API do workspace (wsk_).
Os e-mails enviados por ela não abrem conversas no atendimento e não criam leads nem contatos.
| Método | Rota | Permissão da chave |
|---|---|---|
POST | /email/transactional/messages | email:send |
GET | /email/transactional/messages | email:read |
GET | /email/transactional/messages/{id} | email:read |
Antes de começar
- Um remetente com domínio verificado, cadastrado no aplicativo em Menu lateral › E-mail › Remetentes e domínios. O campo
fromde cada envio precisa ser um remetente do workspace. - Saldo na carteira do workspace. Cada destinatário é cobrado como um e-mail, e os anexos somam um valor por bloco de 256 KB. O valor dos destinatários que não saem depois da cobrança volta para a carteira.
- Uma chave de API com a permissão
email:send, eemail:readse for consultar o registro.
Chave de API
Crie a chave no aplicativo, em Menu lateral › Integrações › Chaves de API, ou por POST /api-keys com o token de login:
curl -X POST "https://api.vozkoia.com/api-keys" \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "X-Workspace-ID: SEU_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{"name": "Loja virtual, produção", "scopes": ["email:send", "email:read"]}'- Criar pede a permissão
api_keys:create; listar (GET /api-keys),api_keys:read; revogar (DELETE /api-keys/{id}),api_keys:delete. - O nome tem de 1 a 80 caracteres. Fora disso,
400com o códigoapi_key_name_invalid. - Cada workspace pode ter até 25 chaves ativas. Acima disso,
409com o códigoapi_key_limit_reached. - A chave completa vem no campo
keyda resposta, uma única vez. Só um hash dela é guardado. Na lista ficam o nome, o prefixo (comowsk_k4n2q7xp3m5a), as permissões, quem criou, a data de criação, o último uso (atualizado no máximo uma vez por minuto) e a data de revogação. - O formato é
wsk_, um identificador de 12 caracteres,_e o segredo. - A chave não expira. A revogação vale na hora e não pode ser desfeita. Para trocar uma chave sem parar o serviço, crie a nova, atualize o seu sistema e só então revogue a antiga.
Envie a chave no cabeçalho Authorization, com o esquema Bearer. A chave já identifica o workspace; o X-Workspace-ID é ignorado.
Authorization: Bearer wsk_k4n2q7xp3m5a_SEGREDO_DA_CHAVERecusas da chave
| Status | code | Quando acontece |
|---|---|---|
401 | api_key_missing | O cabeçalho Authorization não foi enviado ou não usa o esquema Bearer. |
401 | api_key_invalid | A chave não existe ou não está no formato esperado. |
401 | api_key_revoked | A chave foi revogada. |
403 | api_key_scope_missing | A chave não tem a permissão exigida pela rota. |
429 | api_key_rate_limited | O limite de requisições foi atingido. Veja Limites de requisição. |
503 | api_key_unavailable | Não foi possível verificar a chave naquele momento. Tente de novo em instantes. |
Envie um e-mail
curl -X POST "https://api.vozkoia.com/email/transactional/messages" \
-H "Authorization: Bearer SUA_CHAVE_DE_API" \
-H "Content-Type: application/json" \
-d '{
"from": "[email protected]",
"to": ["[email protected]"],
"subject": "Seu código de acesso",
"html": "<p>Seu código é <b>482913</b></p>",
"text": "Seu código é 482913",
"idempotency_key": "codigo-acesso-0001"
}'idempotency_key é obrigatória: ela garante que, se a chamada for repetida, o e-mail não sai nem é cobrado duas vezes. Também pode ir no cabeçalho Idempotency-Key; quando os dois vêm, vale o do corpo. Veja Idempotência.
Campos
| Campo | Para que serve |
|---|---|
from | O remetente: o endereço ou o id de um remetente do workspace. |
to, cc, bcc | Destinatários. Somam até 50, com ao menos um em to. Cada destinatário recebe a própria cópia. Endereços repetidos contam uma vez, sem diferenciar maiúsculas de minúsculas. |
reply_to | Até 5 endereços para onde vão as respostas. |
subject | O assunto, até 998 bytes, sem quebras de linha. |
html, text | O conteúdo. |
design_id e variables | Usa um modelo de e-mail salvo no workspace no lugar de html e text. Não envie os dois jeitos juntos, nem variables sem design_id. |
tags | Até 10 pares name e value, com até 256 caracteres cada, entre letras, números, _ e -. Servem de filtro no registro e voltam nos webhooks. |
headers | Até 20 cabeçalhos. São aceitos X-* (exceto X-SES-*), List-Unsubscribe, List-Unsubscribe-Post, List-Id, Auto-Submitted, Precedence e Entity-Ref-ID. |
attachments | Até 20 anexos, cada um com filename e o conteúdo em base64 (content) ou um endereço https (path), e opcionalmente content_type. Até 16 MB no total. Arquivos executáveis e scripts são recusados pela extensão. |
idempotency_key | De 1 a 256 caracteres ASCII imprimíveis. |
O envio recusa campos que não fazem parte do corpo, com 400 e o código invalid_body; a mensagem diz qual campo foi rejeitado. O corpo inteiro pode ter até 24 MB.
Resposta
Quando ao menos um destinatário sai, a resposta é 201 Created, com o resultado de cada destinatário:
{
"id": "5a0c6f3e-9d1b-4b7a-8e2f-3c4d5e6f7a8b",
"idempotency_key": "codigo-acesso-0001",
"repeated": false,
"messages": [
{
"id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
"to": "[email protected]",
"role": "to",
"status": "sent"
}
]
}ididentifica o envio como um todo; oidde cada item demessagesidentifica o e-mail de um destinatário.- Um destinatário que não saiu vem com
statusrefusede umerror_codecom o motivo. repeatedétruequando a mesmaidempotency_keyjá tinha sido usada para o mesmo pedido. A resposta é então200 OK, e nada é enviado nem cobrado de novo.- Se o provedor atingiu o limite no meio do envio, a resposta traz
retry_after_secondse o cabeçalhoRetry-After. Espere esse tempo e repita com a mesmaidempotency_keypara enviar o restante.
Se nenhum destinatário sair, a resposta é a recusa do primeiro destinatário.
Consulte o registro
GET /email/transactional/messages lista os e-mails do workspace, um item por destinatário, do mais novo para o mais antigo. A paginação é por cursor (veja Paginação):
| Parâmetro | Descrição |
|---|---|
limit | Itens por página, de 1 a 100. O padrão é 50. |
cursor | O next_cursor da página anterior. |
status | Um destes: pending, refused, queued, sent, delivered, bounced, suppressed, failed. |
recipient | Endereço exato do destinatário. |
tag_name e tag_value | Uma tag do envio. Os dois precisam vir juntos. |
after | Só e-mails criados a partir deste instante (RFC 3339). |
before | Só e-mails criados antes deste instante (RFC 3339). Precisa ser posterior a after. |
GET /email/transactional/messages/{id} traz um e-mail, com o status atual e a lista events com a linha do tempo do provedor (kind, occurred_at, link, is_bot e detail).
Para receber esses eventos no seu sistema assim que acontecem, cadastre um webhook.
Quem usa o aplicativo com o token de login lê o mesmo registro em GET /email/transactional/log e GET /email/transactional/log/{id}, com a permissão email_marketing:read.
Recusas do envio
Antes da cobrança
Nada foi enviado nem cobrado. Corrija a requisição e tente de novo.
| Status | code | Significado |
|---|---|---|
400 | invalid_body | O corpo não é um JSON válido para o envio ou tem um campo desconhecido. |
400 | email_idempotency_key_required | Falta a idempotency_key. |
400 | email_idempotency_key_invalid | A idempotency_key precisa de 1 a 256 caracteres imprimíveis. |
400 | email_from_required | Falta o remetente em from. |
400 | email_recipients_invalid | O envio precisa de 1 a 50 destinatários, com ao menos um em to. |
400 | email_address_invalid | Um dos endereços de e-mail é inválido. |
400 | email_reply_to_invalid | reply_to aceita até 5 endereços válidos. |
400 | email_tags_invalid | As tags aceitam até 10 nomes distintos com letras, números, _ e -. |
402 | email_balance_insufficient | A carteira não tem saldo para o envio. details.missing_micros traz o valor que falta. |
404 | email_design_not_found | O modelo informado em design_id não existe. |
409 | email_idempotency_key_reused | A idempotency_key já foi usada em um pedido diferente. |
409 | email_send_in_progress | Um envio com a mesma idempotency_key ainda está em andamento. |
409 | email_sender_not_verified | O domínio do remetente ainda não foi verificado. |
409 | email_recipient_suppressed | O endereço está na lista de supressão, por exemplo depois de uma devolução permanente ou reclamação. |
413 | body_too_large | O corpo declarado passa de 24 MB. details.maxBytes traz o limite em bytes. |
413 | email_attachment_too_large | Os anexos passam de 16 MB, a mensagem montada fica grande demais, ou um corpo enviado sem tamanho declarado passa do limite. |
422 | email_sender_unknown | from não é um remetente deste workspace. |
422 | email_header_not_allowed | Um cabeçalho não é permitido, está repetido, tem valor inválido, ou há mais de 20. |
422 | email_message_invalid | O conteúdo é inválido: sem html, text ou design_id, com design_id junto de html ou text, ou com variables sem design_id. |
422 | email_subject_invalid | O assunto está vazio, passa de 998 bytes ou tem quebra de linha. |
422 | email_attachment_invalid | Um anexo não tem nome, tipo ou conteúdo válido, ou há mais de 20 anexos. |
422 | email_attachment_blocked | O tipo de arquivo não pode ser anexado, como executáveis e scripts. |
422 | email_attachment_unavailable | Não foi possível baixar um anexo informado em path. |
503 | email_charge_failed | A cobrança está indisponível; nada foi enviado. |
Depois da cobrança
O valor dos destinatários que não saíram volta para a carteira.
| Status | code | Significado |
|---|---|---|
409 | email_sender_missing | O workspace não tem um remetente cadastrado. |
409 | email_account_paused | O envio de e-mail do workspace está pausado. |
429 | email_daily_cap_reached | O limite diário de envios do domínio foi atingido. O contador zera à meia-noite, no horário de Brasília. |
429 | email_send_throttled | O provedor está no limite naquele momento. Aguarde Retry-After e repita com a mesma idempotency_key. |
502 | email_send_failed | Não foi possível enviar o e-mail naquele momento. |
503 | email_account_reactivation_failed | Não foi possível reativar o envio de e-mail naquele momento. |
Recusas do registro
| Status | code | Significado |
|---|---|---|
400 | email_log_cursor_invalid | O cursor não é válido. Use o next_cursor sem alterar. |
400 | email_log_filter_invalid | Um filtro é inválido, como uma data fora do RFC 3339, tag_name sem tag_value, before anterior a after ou um limit negativo. |
404 | email_message_not_found | O e-mail não existe neste workspace. |
500 | email_log_failed | Não foi possível ler o registro naquele momento. |
Como tratar
400,402,403,404,413e422: não repita sem corrigir a causa.429: espere os segundos deRetry-Afterantes de repetir.502,503e falhas de rede: repita com a mesmaidempotency_key. Se o envio anterior tiver saído, a API devolve o mesmo resultado sem enviar nem cobrar de novo.
Updated 17 days ago