Modelos de e-mail feitos de blocos, campanhas com público, revisão, teste, disparo e métricas.
O e-mail marketing da Vozko tem duas peças: o modelo (um documento de blocos, salvo para reaproveitar) e a campanha (o documento, o assunto, o remetente e o público de um envio). As rotas estão nos grupos de e-mail da Referência da API e exigem as permissões do recurso email_marketing (read, create, update, delete, start e stop).
O e-mail só sai depois que a conta de envio do workspace está ativa e com o domínio verificado (
GET /email/setup). Antes disso, a revisão da campanha aponta o impedimento.
O documento
Modelos e campanhas guardam o mesmo documento JSON, renderizado sempre no servidor. Ele tem três partes:
| Campo | Regra |
|---|---|
version | Sempre 1. |
settings | Largura, cores, fonte e texto de pré-visualização do e-mail inteiro. |
blocks | A lista de blocos, de cima para baixo. |
Cada bloco tem id, kind e um objeto de propriedades com o nome do tipo: um bloco heading traz o objeto heading, um bloco button traz button, e assim por diante. Os tipos são heading, text, button, image, divider, spacer, columns, social e footer; os campos e as regras de cada um estão em Blocos do e-mail.
Regras do documento inteiro:
- O JSON é lido de forma estrita: campo desconhecido ou tipo de bloco desconhecido responde 400
email_design_malformed. - O
idde cada bloco é único no documento, contando os blocos dentro de colunas. - O documento tem no máximo 200 blocos, contando os de dentro das colunas.
- Há exatamente um rodapé (
footer), e ele é o último bloco. Nas campanhas, o servidor acrescenta abaixo dele o link de descadastro. - Colunas não entram dentro de colunas, e o rodapé não entra em colunas.
{
"version": 1,
"settings": {
"font_family": "inter",
"preheader": "As ofertas da semana chegaram"
},
"blocks": [
{
"id": "titulo",
"kind": "heading",
"heading": { "text": "Olá, {{first_name|cliente}}", "level": 1, "align": "center" }
},
{
"id": "texto",
"kind": "text",
"text": {
"paragraphs": [
{ "runs": [ { "text": "Tudo com " }, { "text": "30% de desconto", "bold": true }, { "text": " até domingo." } ] }
]
}
},
{
"id": "botao",
"kind": "button",
"button": { "label": "Ver ofertas", "href": "https://loja.exemplo.com/ofertas", "align": "center" }
},
{
"id": "rodape",
"kind": "footer",
"footer": { "company_name": "Loja Exemplo", "address": "Rua das Flores, 100, São Paulo, SP" }
}
]
}Problemas do documento
Quando o documento não passa nas regras, a recusa é 422 email_design_invalid e details.issues lista cada problema com code, o bloco (block_id) e o campo (field):
{
"error": true,
"code": "email_design_invalid",
"message": "emaildesign: invalid document: footer_missing",
"details": {
"issues": [ { "code": "footer_missing", "field": "blocks" } ]
}
}Alguns códigos frequentes: footer_missing, footer_not_last, footer_duplicate, block_id_duplicate, text_empty, href_missing, link_scheme_invalid, image_src_not_https, color_invalid, text_too_long, unknown_merge_tag e merge_tag_malformed.
Merge tags
Textos, links e o assunto aceitam merge tags, trocadas pelos dados de cada destinatário no envio:
| Tag | Valor |
|---|---|
{{first_name}} | O primeiro nome. |
{{name}} | O nome completo. |
{{email}} | O e-mail. |
{{company}} | A empresa. |
{{field.chave}} | Um campo personalizado do lead; a chave usa letras minúsculas, números e _. |
Um valor depois de | é o texto usado quando o destinatário não tem o dado: {{first_name|cliente}}. Esse texto vai até 100 caracteres e não pode ter outro |. Uma tag fora da lista responde unknown_merge_tag; chaves sem fechamento ou com quebra de linha, merge_tag_malformed.
Modelos
| Rota | Para que serve |
|---|---|
GET /email/designs/starters | Documentos iniciais prontos (em branco, newsletter, promoção, anúncio, evento). |
GET /email/designs | Os modelos salvos, filtrados por kind. |
POST /email/designs | Salva um modelo. |
GET /email/designs/{designId} | Um modelo. |
PUT /email/designs/{designId} | Substitui um modelo. |
DELETE /email/designs/{designId} | Exclui um modelo. |
POST /email/render | Renderiza um documento com dados de exemplo e devolve HTML, texto, o assunto resolvido e dicas de qualidade, sem salvar nada. |
O corpo de POST e de PUT tem name (até 120 caracteres), kind (template ou campaign), thumbnail_url opcional (um endereço https) e document. Um modelo só é salvo com o documento completo: qualquer problema da lista acima recusa o pedido.
{
"name": "Ofertas da semana",
"kind": "template",
"document": {
"version": 1,
"settings": {},
"blocks": [
{ "id": "titulo", "kind": "heading", "heading": { "text": "Ofertas da semana", "level": 1 } },
{ "id": "rodape", "kind": "footer", "footer": { "company_name": "Loja Exemplo", "address": "Rua das Flores, 100, São Paulo, SP" } }
]
}
}A API sempre recebe o documento inteiro. O assistente do aplicativo edita os modelos por operações (adicionar, alterar, mover, remover e duplicar blocos), mas essas operações não têm rota própria.
Campanhas
Criar e editar
POST /email/campaigns cria um rascunho. Só name é obrigatório (até 120 caracteres); o resto pode vir depois, por PATCH /email/campaigns/{campaignId}, que substitui o conteúdo inteiro do rascunho. Um rascunho aceita um documento incompleto: as pendências aparecem na revisão.
| Campo | Regra |
|---|---|
name | O nome da campanha. |
sender_id | O remetente. |
subject | O assunto, até 150 caracteres, sem quebra de linha. Aceita merge tags. |
preheader | O texto de pré-visualização, até 200 caracteres. Quando preenchido, substitui o preheader do documento. |
document | O documento. |
selection | O público por leads (veja abaixo). |
list_id | O público por uma lista enviada (veja abaixo). Nunca junto com selection. |
merge_policies | O que fazer com quem não tem o valor de uma merge tag. |
ab_test | O teste A/B do assunto. |
utm | campaign e content acrescentados aos links. utm_source e utm_medium são sempre email; sem campaign, vale o nome da campanha em minúsculas e com hífens. |
Campanhas em envio ou encerradas não mudam (409 email_campaign_not_editable). Editar uma campanha pronta (ready) a devolve para rascunho.
Público
O público vem de um de dois lugares:
- Leads, em
selection:modeéids(até 5.000 leads escolhidos emids),all_matching(todos os leads de umfilter),first_n(os primeiroslimitleads do filtro, na ordem desort) oueveryone. O filtro segue a linguagem de Filtros. - Uma lista, em
list_id: o id devolvido porPOST /campaign-audience/email/lists, que lê uma planilha ou um texto colado.
POST /campaign-audience/email/count conta o público antes de criar a campanha.
Para cada merge tag, uma entrada em merge_policies decide o que acontece com quem não tem o valor: missing text usa text no lugar (vale mais que o texto depois de | na tag) e missing exclude deixa a pessoa fora do envio. A chave é o nome da tag, como first_name ou field.cidade.
{
"name": "Ofertas de novembro",
"subject": "{{first_name|Cliente}}, as ofertas chegaram",
"preheader": "Até 30% de desconto até domingo",
"document": {
"version": 1,
"settings": {},
"blocks": [
{ "id": "titulo", "kind": "heading", "heading": { "text": "Ofertas de novembro", "level": 1 } },
{ "id": "rodape", "kind": "footer", "footer": { "company_name": "Loja Exemplo", "address": "Rua das Flores, 100, São Paulo, SP" } }
]
},
"selection": {
"mode": "ids",
"ids": [ "3f6b2f8e-1c3a-4e59-9a57-0d6f3c2b1a90", "7a1c9e44-52b0-4d8e-8f1d-6c2e9b0a3d21" ]
},
"merge_policies": [ { "key": "first_name", "missing": "text", "text": "Cliente" } ],
"ab_test": {
"variant_b_subject": "Só hoje: 30% de desconto",
"test_percent": 20,
"winner_metric": "opens",
"decide_after_minutes": 120
},
"utm": { "campaign": "ofertas-novembro" }
}Teste A/B
Com ab_test, uma parte do público (test_percent, de 10 a 50) recebe o assunto da campanha (variante a) ou variant_b_subject (variante b), meio a meio. Depois de decide_after_minutes (de 30 a 1.440), a variante com mais aberturas ou cliques (winner_metric opens ou clicks) vai para o resto do público. winner é decidido pelos resultados e não pode ser enviado.
Revisão e teste
GET /email/campaigns/{campaignId}/review resolve o público e mostra quem fica de fora e por quê, o custo em micros de dólar e em reais, o saldo e a verificação de disparo: blocking lista os impedimentos e hints as dicas de qualidade. Os impedimentos possíveis:
code | Quando |
|---|---|
sender_missing | Não há remetente. |
sender_not_verified | O domínio do remetente não está verificado. |
account_paused | A conta de envio está pausada. |
document_invalid | O documento tem problemas; issues os lista. |
subject_invalid | O assunto (ou o da variante B) tem problemas. |
audience_empty | Ninguém do público pode receber. |
balance_insufficient | Falta saldo; missing_micros diz quanto. |
schedule_in_past | O agendamento não está no futuro. |
domains_checking | Domínios do público ainda em verificação; some sozinho em instantes. |
POST /email/campaigns/{campaignId}/test envia o e-mail como ficará para até 5 endereços em to. Cada endereço é cobrado do saldo como um e-mail normal, e o que não sair é devolvido.
Disparo e controle
| Rota | Efeito | Permissão |
|---|---|---|
POST .../ready | Refaz a verificação e deixa o rascunho pronto (ready) para iniciar depois, sem cobrar. | start |
POST .../launch | Sem corpo, refaz a verificação, cobra o envio e começa a enviar. Com scheduled_at no futuro, agenda; a cobrança acontece no início. | start |
POST .../unschedule | Devolve a campanha agendada para rascunho. | start |
POST .../pause | Pausa o envio; os pendentes continuam reservados. | stop |
POST .../resume | Retoma uma campanha pausada ou em espera. | start |
POST .../stop | Encerra o envio de vez e devolve ao saldo o valor dos e-mails não enviados. | stop |
Um disparo impedido responde 422 email_campaign_blocked, com os impedimentos em details.issues e as dicas em details.hints. Sem saldo, a resposta é 402 email_balance_insufficient com details.missing_micros.
{ "scheduled_at": "2026-11-20T12:00:00-03:00" }O campo status da campanha percorre estes valores, e actions lista os comandos que o status atual permite:
status | Significado |
|---|---|
draft | Rascunho. |
ready | Pronta para iniciar. |
scheduled | Agendada. |
running | Enviando. |
paused | Pausada por alguém. |
held | Em espera pelo sistema; hold explica o motivo, como o limite diário, a conta pausada, o remetente indisponível ou o saldo. |
completed | Terminou de enviar. |
stopped | Encerrada antes do fim. |
Só rascunhos e campanhas prontas são excluídos (DELETE /email/campaigns/{campaignId}).
Métricas
| Rota | O que traz |
|---|---|
GET .../metrics | Enviados, entregues, aberturas e cliques únicos de pessoas (robôs ficam fora), rejeições, reclamações, descadastros, ignorados por motivo, taxas em pontos-base e o resultado do teste A/B. Atualiza a cada 15 segundos durante o envio. |
GET .../timeline | A série por hora (campanhas de até 48 horas) ou por dia, no fuso de time_zone. |
GET .../links | Os 50 links mais clicados. |
GET .../domains | O resultado por provedor de caixa postal. |
GET .../recipients | Os destinatários, com o estado de cada mensagem, filtrados por status, motivo, variante e endereço. |
GET /email/overview | Os totais do workspace numa janela de 1 a 90 dias e a reputação contra as faixas de atenção. |
As taxas em pontos-base vão de 0 a 10.000: 2.350 quer dizer 23,5%.