# Contatti

> I contatti sono le persone del tuo workspace. Scopri come si collegano contatti, liste e iscritti, cosa mostrano l’elenco e il profilo dei contatti e come funzionano gli opt-out.

Un contatto è una persona del tuo workspace, identificata dal suo indirizzo email. I contatti contengono i nomi e i valori dei campi personalizzati che usi per personalizzare le campagne, e fanno parte delle liste, cioè gli elenchi a cui vengono inviate le campagne. Questa pagina spiega come si combinano questi elementi e cosa puoi fare con i contatti nel pannello e con l’API.

## Contatti, liste e iscritti

Emailit tiene separate persone e liste. Una persona esiste una sola volta come contatto, e ogni lista in cui si trova è un record di iscritto separato con il proprio stato di opt-in.

| | Contatto | Lista | Iscritto |
| --- | --- | --- | --- |
| **Cos’è** | Una persona | Un elenco con un nome a cui invii le campagne | L’appartenenza di un contatto a una lista |
| **Prefisso dell’ID** | `con_` | `aud_` | `sub_` |
| **Unico per** | Indirizzo email, per workspace | Nome, per workspace | Uno per contatto per lista |
| **Contiene** | Email, nome, cognome, campi personalizzati, stato marketing | Nome, numero di iscritti, URL di iscrizione | Un indicatore **Subscribed** con le date di iscrizione e disiscrizione |
| **Se lo elimini** | Il contatto viene rimosso anche da tutte le liste | Vengono rimossi tutti i suoi iscritti. I contatti restano. | Viene rimossa quell’appartenenza. Il contatto resta. |

```text
Workspace
├── Contacts ────────────── one per email address
│   ├── email, first_name, last_name, custom_fields
│   └── marketing status (unsubscribed: true | false)
└── Audiences ───────────── named lists, for example "Newsletter"
    └── Subscribers ─────── one per contact on the list
        └── subscribed: true | false
```

In pratica:

- Un contatto può essere iscritto a molte liste, con un indicatore **Subscribed** separato in ciascuna.
- Aggiungere qualcuno a una lista tramite email crea prima il contatto, se non esiste ancora.
- Nomi e campi personalizzati appartengono al contatto. Modificarli da una lista cambia il contatto, quindi la modifica compare ovunque.

### Chi riceve una campagna

Una campagna viene inviata a ogni contatto che soddisfa tutte e tre le condizioni:

1. Il contatto è iscritto ad almeno una delle liste della campagna, con **Subscribed** attivo.
2. Lo stato marketing del contatto è **Subscribed**.
3. L’indirizzo non è nella [lista di soppressione](/it/docs/suppressions/).

Un contatto presente in più liste selezionate riceve una sola copia. Per le regole complete, vedi [Crea una campagna](/it/docs/campaigns/create/).

## Stato marketing

Ogni contatto ha anche uno stato marketing valido per tutto il workspace, il campo **Marketing status**: **Subscribed** o **Unsubscribed** (il campo `unsubscribed` nell’API). È un opt-out globale che sta sopra l’indicatore delle singole liste.

| Cosa modifichi | Come | Effetto sulle campagne |
| --- | --- | --- |
| Stato marketing | **Unsubscribe** o **Resubscribe** in blocco dall’elenco dei contatti, oppure `unsubscribed` nell’API | I contatti **Unsubscribed** vengono saltati in tutte le liste. La loro appartenenza alle liste non cambia. |
| L’iscrizione a una lista | **Unsubscribe** o **Resubscribe** nella pagina del contatto o nella lista, oppure `subscribed` sull’iscritto | Il contatto viene saltato solo per le campagne inviate a quella lista. |
| Il destinatario seleziona il link di disiscrizione | La pagina di disiscrizione ospitata | Il contatto viene disiscritto da tutte le liste a cui appartiene. |

Stato marketing e iscrizioni alle liste controllano solo le campagne. Non bloccano le email che invii con l’API o SMTP, né quelle inviate dalle automazioni. Per bloccare tutta la posta verso un indirizzo, aggiungilo alle [soppressioni](/it/docs/suppressions/). [Disiscrizioni](/it/docs/audiences/unsubscribes/) descrive tutti i modi di fare opt-out.

## L’elenco Contacts

Apri **Email Marketing → Contacts** per vedere tutti i contatti del workspace, a partire dai più recenti.

- **Colonne.** **Email** è sempre visibile. Attiva o disattiva **First name**, **Last name**, **Audiences**, **Created** e **Updated** in **Display options > Edit columns**, oppure seleziona **Show full name** per unire nome e cognome in un’unica colonna **Name**. Nella colonna **Audiences**, il badge di ogni lista è verde finché il contatto è iscritto e rosso dopo la disiscrizione.
- **La ricerca** trova corrispondenze su email, nome e cognome.
- **Filtra** per Email, Name, First name, Last name, Unsubscribed, Created, Updated, Audiences o Audience, e per qualsiasi [campo personalizzato](/it/docs/contacts/custom-fields/). Con due o più filtri, scegli se devono corrispondere tutti o almeno uno.
- **Ordina** selezionando l’intestazione di una colonna.
- **Import** ed **Export** importano ed esportano i contatti come file. Vedi [Importa ed esporta i contatti](/it/docs/contacts/import-export/).

Seleziona una riga per aprire il contatto. Il menu della riga contiene **Edit** e **Delete**.

### Aggiungi un contatto

Seleziona **Add contact** e compila il campo **Email** e, se vuoi, **First name**, **Last name** e **Audiences**. Seleziona **Show custom fields** per inserire i valori dei campi personalizzati. Un indirizzo email può esistere una sola volta per workspace, quindi l’aggiunta di un indirizzo già presente non riesce.

Per modificare un contatto in seguito, seleziona **Edit**. Puoi cambiare nome, cognome e campi personalizzati. L’indirizzo email non si può cambiare dal pannello: usa invece il campo `email` di [Aggiorna un contatto](/it/docs/api-reference/contacts/update/).

### Azioni di massa

Seleziona i contatti con le caselle di spunta (la casella nell’intestazione seleziona l’intera pagina), poi apri **Actions**. Ogni azione si applica a un massimo di 100 contatti alla volta.

| Azione | Cosa fa |
| --- | --- |
| **Add to audience** | Aggiunge i contatti alla lista che scegli. Le appartenenze esistenti restano invariate. I contatti con stato marketing **Unsubscribed** entrano come iscritti disiscritti. |
| **Remove from audience** | Elimina la loro appartenenza alla lista che scegli. I contatti restano. |
| **Unsubscribe** | Imposta il loro stato marketing su **Unsubscribed**. |
| **Resubscribe** | Riporta il loro stato marketing a **Subscribed**. Le iscrizioni alle liste non cambiano. |
| **Delete** | Elimina i contatti e tutte le loro appartenenze. Questa operazione non si può annullare. |

## La pagina del contatto

La pagina del contatto mostra tutto ciò che Emailit sa di una persona. In alto trovi **Edit** e **Delete**.

| Sezione | Cosa mostra |
| --- | --- |
| **Details** | Email, nome, cognome, stato marketing, date di creazione e di aggiornamento. |
| **Custom fields** | Tutti i campi personalizzati definiti nel workspace e il valore del contatto. |
| **Metrics and Insights** | **Emails sent**, **Loads**, **Clicks**, **Last activity**, **Subscribed audiences** (iscrizioni attive sul totale) e **Marketing status**. I conteggi includono tutte le email in uscita inviate all’indirizzo, non solo le campagne. |
| **Audiences** | Ogni lista a cui appartiene il contatto, con il suo stato e le date di iscrizione e disiscrizione. Dal menu della riga puoi scegliere **Unsubscribe** o **Resubscribe** per quella lista, oppure **Remove from audience**. **Add to audience** aggiunge una nuova appartenenza. |
| **Sent emails** | Le email in uscita inviate all’indirizzo, con oggetto, stato, campagna, caricamenti, clic e ora di invio. |
| **Activity log** | Una cronologia degli eventi del contatto, come «Contact created», «Added to Newsletter», «Unsubscribed from Newsletter» ed «Email delivered». |

## Usa l’API

L’[API dei contatti](/it/docs/api-reference/contacts/) copre tutto ciò che fanno l’elenco e il profilo, tranne l’importazione di file:

- [Crea](/it/docs/api-reference/contacts/create/), [recupera](/it/docs/api-reference/contacts/get/), [aggiorna](/it/docs/api-reference/contacts/update/), [elenca](/it/docs/api-reference/contacts/list/) ed [elimina](/it/docs/api-reference/contacts/delete/) i contatti. Dove è previsto un ID, puoi passare l’indirizzo email del contatto al posto del suo ID `con_`.
- Passa `audiences` (un array di ID `aud_`) quando crei un contatto per iscriverlo subito. Nell’aggiornamento, `audiences` sostituisce le appartenenze del contatto.
- [Esegui un’azione di massa](/it/docs/api-reference/contacts/bulk/) su un massimo di 100 contatti ed [esportane](/it/docs/api-reference/contacts/export/) fino a 10.000 in CSV o XLSX.

```bash
curl https://api.emailit.com/v2/contacts \
  -X POST \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada@example.com",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "custom_fields": { "company": "Acme", "plan": "pro" },
    "audiences": ["aud_2kq8Vt4xLm7Rz"]
  }'
```

Creare un contatto con un’email già esistente restituisce `409` con il contatto esistente in `existing`. L’API dei contatti richiede una chiave API con **Full Access**.

Le modifiche ai contatti generano gli eventi [`contact.created`, `contact.updated` e `contact.deleted`](/it/docs/webhooks/events/contact/), e le modifiche alle appartenenze generano gli eventi [`subscriber.*`](/it/docs/webhooks/events/subscriber/), che puoi ricevere con i [webhook](/it/docs/webhooks/).

## Passaggi successivi

  - [Campi personalizzati](/it/docs/contacts/custom-fields/): Memorizza dati aggiuntivi sui contatti e usali nei filtri e nelle email.
  - [Importa ed esporta](/it/docs/contacts/import-export/): Importa i contatti da un file CSV o Excel e scaricali.
  - [Liste](/it/docs/audiences/): Raggruppa i contatti in liste a cui inviare le campagne.
  - [Disiscrizioni](/it/docs/audiences/unsubscribes/): Come funzionano gli opt-out e come rispettarli.

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