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étodoRotaPermissão da chave
POST/email/transactional/messagesemail:send
GET/email/transactional/messagesemail:read
GET/email/transactional/messages/{id}email:read

Antes de começar

  1. Um remetente com domínio verificado, cadastrado no aplicativo em Menu lateral › E-mail › Remetentes e domínios. O campo from de cada envio precisa ser um remetente do workspace.
  2. 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.
  3. Uma chave de API com a permissão email:send, e email:read se 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, 400 com o código api_key_name_invalid.
  • Cada workspace pode ter até 25 chaves ativas. Acima disso, 409 com o código api_key_limit_reached.
  • A chave completa vem no campo key da resposta, uma única vez. Só um hash dela é guardado. Na lista ficam o nome, o prefixo (como wsk_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_CHAVE

Recusas da chave

StatuscodeQuando acontece
401api_key_missingO cabeçalho Authorization não foi enviado ou não usa o esquema Bearer.
401api_key_invalidA chave não existe ou não está no formato esperado.
401api_key_revokedA chave foi revogada.
403api_key_scope_missingA chave não tem a permissão exigida pela rota.
429api_key_rate_limitedO limite de requisições foi atingido. Veja Limites de requisição.
503api_key_unavailableNã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

CampoPara que serve
fromO remetente: o endereço ou o id de um remetente do workspace.
to, cc, bccDestinatá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_toAté 5 endereços para onde vão as respostas.
subjectO assunto, até 998 bytes, sem quebras de linha.
html, textO conteúdo.
design_id e variablesUsa 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.
tagsAté 10 pares name e value, com até 256 caracteres cada, entre letras, números, _ e -. Servem de filtro no registro e voltam nos webhooks.
headersAté 20 cabeçalhos. São aceitos X-* (exceto X-SES-*), List-Unsubscribe, List-Unsubscribe-Post, List-Id, Auto-Submitted, Precedence e Entity-Ref-ID.
attachmentsAté 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_keyDe 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"
    }
  ]
}
  • id identifica o envio como um todo; o id de cada item de messages identifica o e-mail de um destinatário.
  • Um destinatário que não saiu vem com status refused e um error_code com o motivo.
  • repeated é true quando a mesma idempotency_key já tinha sido usada para o mesmo pedido. A resposta é então 200 OK, e nada é enviado nem cobrado de novo.
  • Se o provedor atingiu o limite no meio do envio, a resposta traz retry_after_seconds e o cabeçalho Retry-After. Espere esse tempo e repita com a mesma idempotency_key para 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âmetroDescrição
limitItens por página, de 1 a 100. O padrão é 50.
cursorO next_cursor da página anterior.
statusUm destes: pending, refused, queued, sent, delivered, bounced, suppressed, failed.
recipientEndereço exato do destinatário.
tag_name e tag_valueUma tag do envio. Os dois precisam vir juntos.
afterSó e-mails criados a partir deste instante (RFC 3339).
beforeSó 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.

StatuscodeSignificado
400invalid_bodyO corpo não é um JSON válido para o envio ou tem um campo desconhecido.
400email_idempotency_key_requiredFalta a idempotency_key.
400email_idempotency_key_invalidA idempotency_key precisa de 1 a 256 caracteres imprimíveis.
400email_from_requiredFalta o remetente em from.
400email_recipients_invalidO envio precisa de 1 a 50 destinatários, com ao menos um em to.
400email_address_invalidUm dos endereços de e-mail é inválido.
400email_reply_to_invalidreply_to aceita até 5 endereços válidos.
400email_tags_invalidAs tags aceitam até 10 nomes distintos com letras, números, _ e -.
402email_balance_insufficientA carteira não tem saldo para o envio. details.missing_micros traz o valor que falta.
404email_design_not_foundO modelo informado em design_id não existe.
409email_idempotency_key_reusedA idempotency_key já foi usada em um pedido diferente.
409email_send_in_progressUm envio com a mesma idempotency_key ainda está em andamento.
409email_sender_not_verifiedO domínio do remetente ainda não foi verificado.
409email_recipient_suppressedO endereço está na lista de supressão, por exemplo depois de uma devolução permanente ou reclamação.
413body_too_largeO corpo declarado passa de 24 MB. details.maxBytes traz o limite em bytes.
413email_attachment_too_largeOs anexos passam de 16 MB, a mensagem montada fica grande demais, ou um corpo enviado sem tamanho declarado passa do limite.
422email_sender_unknownfrom não é um remetente deste workspace.
422email_header_not_allowedUm cabeçalho não é permitido, está repetido, tem valor inválido, ou há mais de 20.
422email_message_invalidO conteúdo é inválido: sem html, text ou design_id, com design_id junto de html ou text, ou com variables sem design_id.
422email_subject_invalidO assunto está vazio, passa de 998 bytes ou tem quebra de linha.
422email_attachment_invalidUm anexo não tem nome, tipo ou conteúdo válido, ou há mais de 20 anexos.
422email_attachment_blockedO tipo de arquivo não pode ser anexado, como executáveis e scripts.
422email_attachment_unavailableNão foi possível baixar um anexo informado em path.
503email_charge_failedA 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.

StatuscodeSignificado
409email_sender_missingO workspace não tem um remetente cadastrado.
409email_account_pausedO envio de e-mail do workspace está pausado.
429email_daily_cap_reachedO limite diário de envios do domínio foi atingido. O contador zera à meia-noite, no horário de Brasília.
429email_send_throttledO provedor está no limite naquele momento. Aguarde Retry-After e repita com a mesma idempotency_key.
502email_send_failedNão foi possível enviar o e-mail naquele momento.
503email_account_reactivation_failedNão foi possível reativar o envio de e-mail naquele momento.

Recusas do registro

StatuscodeSignificado
400email_log_cursor_invalidO cursor não é válido. Use o next_cursor sem alterar.
400email_log_filter_invalidUm filtro é inválido, como uma data fora do RFC 3339, tag_name sem tag_value, before anterior a after ou um limit negativo.
404email_message_not_foundO e-mail não existe neste workspace.
500email_log_failedNão foi possível ler o registro naquele momento.

Como tratar

  • 400, 402, 403, 404, 413 e 422: não repita sem corrigir a causa.
  • 429: espere os segundos de Retry-After antes de repetir.
  • 502, 503 e falhas de rede: repita com a mesma idempotency_key. Se o envio anterior tiver saído, a API devolve o mesmo resultado sem enviar nem cobrar de novo.

Did this page help you?