Campos personalizados

Os campos personalizados guardam dados extras em cada contato, como o nome de uma empresa, um plano ou uma data de aniversário. Você define os campos uma vez para o workspace, depois os preenche nos contatos e os usa para filtrar contatos, personalizar campanhas e iniciar automações.

Tipos de campo

Cada campo tem um nome, que o painel mostra, e uma chave, que a API, as importações, os filtros e as tags de mesclagem usam. Os valores são armazenados no contato como um objeto JSON indexado pela chave do campo:

{
  "company": "Acme",
  "plan": "pro",
  "birthday": "1990-04-12",
  "interests": ["news", "offers"]
}

Criar um campo personalizado

1. Abra Custom fields. Acesse Workspace›Settings›Custom fields e selecione Add custom field.

2. Dê um nome ao campo. Em Name, digite um nome, por exemplo Company size. O Emailit monta a chave a partir do nome automaticamente: em minúsculas, com cada sequência de outros caracteres substituída por _, então Company size vira company_size.

   Para escolher a chave você mesmo, selecione Show advanced options e edite Key. As chaves são sempre salvas nesse formato em minúsculas com sublinhados, e cada chave só pode existir uma vez por workspace.

3. Escolha o tipo. Escolha Text, Number, Date, Boolean, Select ou Multi select.

4. Adicione opções aos campos de seleção. Em Select e Multi select, digite pelo menos uma opção e use Add option para adicionar mais. Esses valores aparecem na lista suspensa dos contatos.

5. Salve. Selecione Create. O campo aparece em todos os contatos, nos filtros de contatos e como tag de mesclagem nos editores de campanha.

A página Custom fields lista todos os campos com nome, tipo e opções. Use Edit para renomear um campo, alterar o tipo ou a chave dele, ou editar as opções.

Definir valores

Pela API, passe custom_fields para Criar um contato ou Atualizar um contato:

curl https://api.emailit.com/v2/contacts/ada@example.com \
  -X POST \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "custom_fields": {
      "company": "Acme",
      "plan": "pro",
      "birthday": "1990-04-12",
      "interests": ["news", "offers"]
    }
  }'

Regras importantes:

• custom_fields substitui o objeto inteiro. Na atualização, inclua todos os valores que você quer manter, não apenas os que mudam.
• Use as chaves dos campos, não os nomes. Os valores de chaves que não estão definidas em Custom fields são armazenados, mas não aparecem no painel.
• As datas precisam estar no formato YYYY-MM-DD. O Emailit converte data e hora ISO e células de data do Excel em uma data. Qualquer outra coisa retorna 400 com “Custom field “Birthday” must be a date in YYYY-MM-DD format”. As datas não têm hora nem fuso horário.
• Os valores de seleção não são conferidos com as opções. Um valor que não está na lista de opções é armazenado mesmo assim, e o painel continua a exibi-lo.

Filtrar contatos por um campo personalizado

No painel, abra Email Marketing›Contacts, selecione Filter e escolha o campo personalizado pelo nome. Os filtros de campos personalizados comparam o valor armazenado como texto, então use equals, does not equal, contains, does not contain, starts with, ends with, is empty ou is not empty.

Pela API, use custom_fields.<key>.<condition> em Listar contatos e Exportar contatos, com as mesmas condições de texto (exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty):

curl "https://api.emailit.com/v2/contacts?custom_fields.plan.exact=pro&custom_fields.company.contains=acme" \
  -H "Authorization: Bearer $EMAILIT_API_KEY"

Para um intervalo, como aniversários nos anos 1990, use os parâmetros filter[custom_fields.<key>][gte] e [lte]. Eles comparam o texto armazenado, que fica na ordem correta para datas YYYY-MM-DD:

curl -G "https://api.emailit.com/v2/contacts" \
  --data-urlencode "filter[custom_fields.birthday][gte]=1990-01-01" \
  --data-urlencode "filter[custom_fields.birthday][lte]=1999-12-31" \
  -H "Authorization: Bearer $EMAILIT_API_KEY"

Consulte Filtragem para saber como os filtros se combinam.

Usar campos personalizados em campanhas

No conteúdo e no assunto das campanhas, insira um campo personalizado com a tag de mesclagem {{cf.<key>}}, por exemplo {{cf.company}}. Os editores de texto formatado e Dragit listam os seus campos personalizados entre as variáveis, então você não precisa digitar a chave.

<p>Hi {{first_name}}, here's what's new for {{cf.company}}.</p>

Se um contato não tiver valor, a tag é substituída por nada. Os valores de seleção múltipla aparecem como uma lista separada por vírgulas. Consulte Tags de mesclagem.

Usar campos personalizados em automações

• Gatilho de aniversário de data. Escolha um campo Date para iniciar uma execução todo ano no mês e no dia armazenados nele, por exemplo uma data de aniversário. Consulte Gatilhos.
• Gatilho de contato atualizado. Filtre por um campo personalizado, ou pelo valor anterior dele, para reagir quando ele mudar.
• Etapa de condição. Crie ramificações com base no valor de um campo personalizado.
• Etapa de edição de contato. Defina um campo personalizado informando a chave dele.

Referência da API

As definições de campos personalizados são gerenciadas apenas no painel. Os valores dos contatos usam o objeto custom_fields na API de contatos, e o mesmo objeto é aceito quando você adiciona um inscrito a uma lista.

Veja também