Campi personalizzati

I campi personalizzati memorizzano dati aggiuntivi su ogni contatto, come il nome di un’azienda, un piano o un compleanno. Definisci i campi una volta per il workspace, poi li compili sui contatti e li usi per filtrare i contatti, personalizzare le campagne e avviare le automazioni.

Tipi di campo

Ogni campo ha un nome, che il pannello mostra, e una chiave, che usano l’API, le importazioni, i filtri e i tag di unione. I valori vengono memorizzati sul contatto come oggetto JSON indicizzato per chiave del campo:

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

Crea un campo personalizzato

1. Apri Custom fields. Vai a Workspace›Settings›Custom fields e seleziona Add custom field.

2. Dai un nome al campo. Compila il campo Name, ad esempio Company size. Emailit ricava automaticamente la chiave dal nome: in minuscolo, con ogni sequenza di altri caratteri sostituita da _, quindi Company size diventa company_size.

   Per scegliere tu la chiave, seleziona Show advanced options e modifica Key. Le chiavi vengono sempre salvate in questa forma minuscola con trattini bassi, e ogni chiave può esistere una sola volta per workspace.

3. Scegli il tipo. Scegli Text, Number, Date, Boolean, Select o Multi select.

4. Aggiungi le opzioni per i campi di selezione. Per Select e Multi select, inserisci almeno un’opzione e usa Add option per aggiungerne altre. Questi valori compaiono nel menu a tendina dei contatti.

5. Salva. Seleziona Create. Il campo compare su ogni contatto, nei filtri dei contatti e come tag di unione negli editor delle campagne.

La pagina Custom fields elenca tutti i campi con nome, tipo e opzioni. Usa Edit per rinominare un campo, cambiarne il tipo o la chiave, o modificarne le opzioni.

Imposta i valori

Con l’API, passa custom_fields a Crea un contatto o ad Aggiorna un contatto:

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"]
    }
  }'

Regole da conoscere:

• custom_fields sostituisce l’intero oggetto. Nell’aggiornamento, includi tutti i valori che vuoi mantenere, non solo quelli che cambiano.
• Usa le chiavi dei campi, non i nomi. I valori per chiavi non definite in Custom fields vengono memorizzati, ma non compaiono nel pannello.
• Le date devono essere nel formato YYYY-MM-DD. Emailit converte in data le date-ora ISO e le celle data di Excel. Qualsiasi altro valore restituisce 400 con «Custom field “Birthday” must be a date in YYYY-MM-DD format». Le date non hanno ora né fuso orario.
• I valori di selezione non vengono confrontati con le opzioni. Un valore che non è nell’elenco delle opzioni viene comunque memorizzato, e il pannello continua a mostrarlo.

Filtra i contatti per campo personalizzato

Nel pannello, apri Email Marketing›Contacts, seleziona Filter e scegli il campo personalizzato per nome. I filtri sui campi personalizzati confrontano il valore memorizzato come testo, quindi usa equals, does not equal, contains, does not contain, starts with, ends with, is empty o is not empty.

Con l’API, usa custom_fields.<key>.<condition> in Elenca i contatti ed Esporta i contatti, con le stesse condizioni testuali (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"

Per un intervallo, ad esempio i compleanni negli anni Novanta, usa i parametri filter[custom_fields.<key>][gte] e [lte]. Confrontano il testo memorizzato, che si ordina correttamente per le date 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"

Per sapere come si combinano i filtri, vedi Filtri e ordinamento.

Usa i campi personalizzati nelle campagne

Nei contenuti e negli oggetti delle campagne, inserisci un campo personalizzato con il tag di unione {{cf.<key>}}, ad esempio {{cf.company}}. Gli editor rich-text e Dragit elencano i campi personalizzati tra le loro variabili, quindi non devi scrivere la chiave.

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

Se un contatto non ha un valore, il tag viene sostituito con niente. I valori a selezione multipla vengono mostrati come elenco separato da virgole. Vedi Tag di unione.

Usa i campi personalizzati nelle automazioni

• Trigger Date anniversary. Scegli un campo Date per avviare un’esecuzione ogni anno nel mese e nel giorno memorizzati, ad esempio un compleanno. Vedi Trigger.
• Trigger Contact updated. Filtra su un campo personalizzato, o sul suo valore precedente, per reagire quando cambia.
• Passaggio Condition. Crea una diramazione in base al valore di un campo personalizzato.
• Passaggio Edit contact. Imposta un campo personalizzato inserendone la chiave.

Riferimento API

Le definizioni dei campi personalizzati si gestiscono solo dal pannello. I valori dei contatti usano l’oggetto custom_fields dell’API dei contatti, e lo stesso oggetto è accettato quando aggiungi un iscritto a una lista.

Vedi anche