Guia de e-mail marketing

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:

CampoRegra
versionSempre 1.
settingsLargura, cores, fonte e texto de pré-visualização do e-mail inteiro.
blocksA 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 id de 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:

TagValor
{{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

RotaPara que serve
GET /email/designs/startersDocumentos iniciais prontos (em branco, newsletter, promoção, anúncio, evento).
GET /email/designsOs modelos salvos, filtrados por kind.
POST /email/designsSalva um modelo.
GET /email/designs/{designId}Um modelo.
PUT /email/designs/{designId}Substitui um modelo.
DELETE /email/designs/{designId}Exclui um modelo.
POST /email/renderRenderiza 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.

CampoRegra
nameO nome da campanha.
sender_idO remetente.
subjectO assunto, até 150 caracteres, sem quebra de linha. Aceita merge tags.
preheaderO texto de pré-visualização, até 200 caracteres. Quando preenchido, substitui o preheader do documento.
documentO documento.
selectionO público por leads (veja abaixo).
list_idO público por uma lista enviada (veja abaixo). Nunca junto com selection.
merge_policiesO que fazer com quem não tem o valor de uma merge tag.
ab_testO teste A/B do assunto.
utmcampaign 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 em ids), all_matching (todos os leads de um filter), first_n (os primeiros limit leads do filtro, na ordem de sort) ou everyone. O filtro segue a linguagem de Filtros.
  • Uma lista, em list_id: o id devolvido por POST /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:

codeQuando
sender_missingNão há remetente.
sender_not_verifiedO domínio do remetente não está verificado.
account_pausedA conta de envio está pausada.
document_invalidO documento tem problemas; issues os lista.
subject_invalidO assunto (ou o da variante B) tem problemas.
audience_emptyNinguém do público pode receber.
balance_insufficientFalta saldo; missing_micros diz quanto.
schedule_in_pastO agendamento não está no futuro.
domains_checkingDomí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

RotaEfeitoPermissão
POST .../readyRefaz a verificação e deixa o rascunho pronto (ready) para iniciar depois, sem cobrar.start
POST .../launchSem 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 .../unscheduleDevolve a campanha agendada para rascunho.start
POST .../pausePausa o envio; os pendentes continuam reservados.stop
POST .../resumeRetoma uma campanha pausada ou em espera.start
POST .../stopEncerra 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:

statusSignificado
draftRascunho.
readyPronta para iniciar.
scheduledAgendada.
runningEnviando.
pausedPausada por alguém.
heldEm espera pelo sistema; hold explica o motivo, como o limite diário, a conta pausada, o remetente indisponível ou o saldo.
completedTerminou de enviar.
stoppedEncerrada antes do fim.

Só rascunhos e campanhas prontas são excluídos (DELETE /email/campaigns/{campaignId}).

Métricas

RotaO que traz
GET .../metricsEnviados, 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 .../timelineA série por hora (campanhas de até 48 horas) ou por dia, no fuso de time_zone.
GET .../linksOs 50 links mais clicados.
GET .../domainsO resultado por provedor de caixa postal.
GET .../recipientsOs destinatários, com o estado de cada mensagem, filtrados por status, motivo, variante e endereço.
GET /email/overviewOs 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%.