Importa ed esporta i contatti

Usa la procedura guidata di importazione per caricare i contatti da un foglio di calcolo, e l’esportazione per scaricare i contatti che corrispondono ai filtri attuali. Questa pagina descrive anche le azioni di massa e l’endpoint di esportazione dell’API, per fare lo stesso dal codice.

Prima di iniziare

• Crea i campi personalizzati che vuoi compilare dal file. La procedura guidata può associare le colonne solo a campi già esistenti.
• Crea le liste a cui vuoi iscrivere i contatti. Le importazioni contano per il limite di iscritti di ogni lista.
• Importa solo persone che hanno accettato di ricevere tue comunicazioni. Le revisioni per l’accesso alla produzione chiedono come raccogli gli iscritti. Vedi Accesso alla produzione.

Prepara il file

La procedura guidata legge file .csv, .xlsx e .xls con un massimo di 2500 contatti per file. Dividi le liste più grandi in più file.

email,first_name,last_name,company,birthday
ada@example.com,Ada,Lovelace,Acme,1990-04-12
grace@example.com,Grace,Hopper,Acme,1906-12-09
alan@example.com,Alan,Turing,,

Consigli per un’importazione pulita:

• Metti un contatto per riga e i nomi delle colonne nella prima riga. Dei file Excel viene letto solo il primo foglio.
• Chiama le colonne come i tuoi campi, così la procedura guidata le associa per te. L’intestazione di una colonna viene associata automaticamente quando corrisponde al nome o alla chiave di un campo, senza distinzione tra maiuscole e minuscole, ad esempio email, First name, first_name o la chiave di un campo personalizzato come company.
• Salva i file CSV in UTF-8, così i nomi con accenti vengono importati correttamente.
• Scrivi le date nel formato YYYY-MM-DD. Funzionano anche le celle data dei file Excel. Gli altri formati di data vengono rifiutati.
• Controlla gli indirizzi. Un solo indirizzo email non valido blocca l’intera importazione con un errore che indica la riga, ad esempio «Contact #12 has an invalid email address.» Le righe con la cella email vuota vengono saltate.
• I valori a selezione multipla vengono importati come un unico valore di testo. Per memorizzare più opzioni come elenco, impostale con l’API.

Importa i contatti

1. Apri la procedura guidata. Vai a Email Marketing›Contacts e seleziona Import.

2. Scegli il file. In CSV File, seleziona il file. Lascia selezionato File has header se la prima riga contiene i nomi delle colonne. La procedura guidata mostra le prime righe e il numero totale di righe, con un avviso se il file ha più di 2500 righe. Seleziona Continue.

3. Associa le colonne. Per ogni colonna, scegli il campo del contatto che compila: Email, First name, Last name, uno dei tuoi campi personalizzati, oppure Exclude per saltarla. Devi associare una colonna a Email. Ogni riga mostra valori di esempio per controllare l’associazione.

4. Scegli le liste. In Audiences, scegli le liste a cui iscrivere i contatti, oppure lascia vuoto per importare i contatti senza aggiungerli a una lista. Seleziona Continue.

5. Controlla e importa. L’anteprima mostra il file, il numero di contatti, le liste, l’associazione delle colonne e i primi 10 contatti così come verranno salvati. Seleziona Import.

Emailit convalida prima l’intero file. Se qualcosa non va, ad esempio un indirizzo non valido, un campo personalizzato sconosciuto o una lista piena, non viene importato nulla e gli errori vengono elencati così puoi correggere il file. Altrimenti l’importazione viene eseguita in background in batch da 500. Aggiorna l’elenco dei contatti dopo qualche istante per vedere i nuovi contatti.

Cosa succede ai contatti esistenti

I contatti vengono abbinati per indirizzo email, senza distinzione tra maiuscole e minuscole.

Altre cose da sapere:

• L’elenco delle associazioni include Unsubscribed, ma l’importazione non lo applica. Per segnare come disiscritte le persone importate, selezionale poi nell’elenco dei contatti e usa l’azione di massa Unsubscribe.
• Le importazioni non inviano eventi webhook contact.* o subscriber.* e non avviano automazioni come Added to audience.
• Se una lista dovesse superare il limite di iscritti, l’importazione viene rifiutata con il limite nel messaggio, ad esempio «Pay as you go includes 10,000 subscribers per audience.» Vedi Liste.

Esporta i contatti

1. Restringi l’elenco. In Email Marketing›Contacts, usa la ricerca e Filter per mostrare i contatti che vuoi. Senza ricerca né filtri, l’esportazione include tutti i contatti.

2. Esporta. Seleziona Export e scegli CSV o XLSX. Il browser scarica contacts.csv o contacts.xlsx.

Un’esportazione può includere fino a 10.000 contatti. Se corrispondono più contatti, l’esportazione non riesce, quindi aggiungi filtri, ad esempio una lista o un intervallo di date di creazione, ed esporta in più parti.

Il file ha una riga per contatto e queste colonne:

Usa l’API

L’API non ha un’importazione da file. Per aggiungere molti contatti dal codice, chiama Crea un contatto per ciascuno, oppure Aggiungi un iscritto per creare il contatto e la sua appartenenza alla lista con una sola chiamata.

Azioni di massa

POST /v2/contacts/bulk esegue un’azione su un massimo di 100 contatti, indicati per ID con_:

curl https://api.emailit.com/v2/contacts/bulk \
  -X POST \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "add_to_audience",
    "ids": ["con_2kq8Vt4xLm7Rz", "con_9fW3pQ1nBc6Yt"],
    "audience_id": "aud_5hJ2kL8mNp4Qr"
  }'

{
  "object": "contact_bulk",
  "action": "add_to_audience",
  "processed": 2,
  "ids": ["con_2kq8Vt4xLm7Rz", "con_9fW3pQ1nBc6Yt"]
}

La richiesta non riesce nel suo complesso se ids ha più di 100 elementi (400) o se un contatto o la lista non esistono (404, con gli ID sconosciuti in missing). Per elaborare più contatti, scorri le pagine di Elenca i contatti e invia batch da 100.

Esportazione

GET /v2/contacts/export restituisce lo stesso file del pannello. Imposta format su csv (il valore predefinito) o xlsx, e aggiungi i filtri, la ricerca e l’ordinamento di Elenca i contatti:

curl "https://api.emailit.com/v2/contacts/export?format=csv&audience_id=aud_5hJ2kL8mNp4Qr&unsubscribed=false" \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -o contacts.csv

Se corrispondono più di 10.000 contatti, l’endpoint restituisce 422 con «Export is limited to 10000 contacts. Narrow your filters and try again.»

Vedi anche