# Importa ed esporta i contatti

> Importa i contatti da un file CSV o Excel con la procedura guidata, esporta i contatti filtrati in CSV o XLSX ed esegui azioni di massa ed esportazioni con l’API.

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](/it/docs/contacts/custom-fields/) che vuoi compilare dal file. La procedura guidata può associare le colonne solo a campi già esistenti.
- Crea le [liste](/it/docs/audiences/) 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](/it/docs/workspaces/production-access/).

## 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.

```csv title="contacts.csv"
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.

| Caso | Risultato |
| --- | --- |
| L’indirizzo è nuovo | Viene creato un contatto. |
| L’indirizzo esiste già | Il contatto viene aggiornato. Nome e cognome vengono sovrascritti solo se il file contiene un valore. I valori dei campi personalizzati del file sostituiscono quelli memorizzati, e una cella vuota in una colonna associata a un campo personalizzato svuota quel campo. Gli altri campi personalizzati vengono mantenuti. |
| L’indirizzo compare due volte nel file | Entrambe le righe vengono applicate in ordine, quindi prevale la riga successiva. |
| Il contatto non è ancora nella lista selezionata | Viene iscritto alla lista. |
| Il contatto si era disiscritto dalla lista selezionata | Viene iscritto di nuovo a quella lista. |

> **Le importazioni reiscrivono le persone:** Importare un contatto in una lista da cui si era disiscritto lo iscrive di nuovo. Prima di importare in una lista esistente, rimuovi dal file le persone che hanno fatto opt-out, oppure importa senza scegliere quella lista.

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](/it/docs/audiences/#limits).

## 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:

| Colonna | Valore |
| --- | --- |
| `email` | L’indirizzo email del contatto. |
| `first_name`, `last_name` | Nome e cognome del contatto. |
| `unsubscribed` | `true` se lo stato marketing è **Unsubscribed**, altrimenti `false`. |
| `audiences` | I nomi di tutte le liste a cui appartiene il contatto, separati da `; `. |
| Una colonna per ogni chiave di campo personalizzato | Il valore memorizzato. I valori a selezione multipla sono uniti con `;`. |
| `created_at`, `updated_at` | Timestamp ISO 8601. |

## Usa l’API

L’API non ha un’importazione da file. Per aggiungere molti contatti dal codice, chiama [Crea un contatto](/it/docs/api-reference/contacts/create/) per ciascuno, oppure [Aggiungi un iscritto](/it/docs/api-reference/audiences/subscribers/add/) per creare il contatto e la sua appartenenza alla lista con una sola chiamata.

### Azioni di massa

[`POST /v2/contacts/bulk`](/it/docs/api-reference/contacts/bulk/) esegue un’azione su un massimo di 100 contatti, indicati per ID `con_`:

| `action` | Effetto | Richiede `audience_id` |
| --- | --- | --- |
| `add_to_audience` | Aggiunge i contatti alla lista. I contatti con `unsubscribed: true` entrano come disiscritti. | Sì |
| `remove_from_audience` | Elimina la loro appartenenza alla lista. | Sì |
| `unsubscribe` | Imposta `unsubscribed: true` (stato marketing **Unsubscribed**). | No |
| `resubscribe` | Imposta `unsubscribed: false`. | No |
| `delete` | Elimina i contatti e le loro appartenenze. | No |

```bash
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"
  }'
```

```json
{
  "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](/it/docs/api-reference/contacts/list/) e invia batch da 100.

### Esportazione

[`GET /v2/contacts/export`](/it/docs/api-reference/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](/it/docs/api-reference/contacts/list/):

```bash
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

  - [Campi personalizzati](/it/docs/contacts/custom-fields/): Definisci i campi a cui associare le colonne.
  - [Iscritti](/it/docs/audiences/subscribers/): Gestisci chi fa parte di ogni lista.

---
Fonte: https://emailit.com/it/docs/contacts/import-export/