# Contatti API

> Gestisci i profili dei contatti e i campi personalizzati, in blocco o uno alla volta.

URL di base: `https://api.emailit.com/v2`. Autenticati con `Authorization: Bearer <API key>`.

## Crea un contatto — POST /contacts

> Crea un contatto con indirizzo email, nomi e campi personalizzati e, facoltativamente, iscrivilo subito a una o più liste.

# Crea un contatto

Crea un contatto e, facoltativamente, lo iscrive a delle liste.

`POST /contacts`

Richiede una chiave API `full`. Gli indirizzi email sono univoci nel workspace e vengono salvati in minuscolo; creare un contatto che esiste già restituisce `409` con il contatto esistente in `existing`. Genera `contact.created` e un `subscriber.created` per ogni lista. Vedi [Contatti](/it/docs/contacts/).

## Parametri del corpo

- `email` (string, obbligatorio): L’indirizzo email del contatto.

- `first_name` (string): Il nome.

- `last_name` (string): Il cognome.

- `custom_fields` (object): Valori per chiave del [campo personalizzato](/it/docs/contacts/custom-fields/), ad esempio `{"company": "Analytical Engines"}`. I valori dei campi di tipo data devono essere nel formato `YYYY-MM-DD`. Le chiavi che non corrispondono a un campo personalizzato vengono salvate così come sono.

- `audiences` (string[]): ID delle liste (`aud_…`) a cui iscrivere il contatto. Gli ID che non esistono nel workspace vengono saltati.

- `unsubscribed` (boolean): `true` per creare il contatto come disiscritto. Le campagne saltano i contatti disiscritti, e la loro appartenenza alle liste parte come disiscritta.

## Restituisce

Restituisce `201` con l’oggetto contatto. Qui `audiences` elenca ogni lista con `id`, `name` e lo stato `subscribed`. Per tutti i campi, vedi [Recupera un contatto](/it/docs/api-reference/contacts/get/).

Restituisce `422` con `usage` quando una lista ha raggiunto il limite di iscritti del piano. In quel caso non viene creato nessun contatto.

**Richiesta** `POST /contacts`

**Node.js**

```javascript
import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const contact = await emailit.contacts.create({
  email: 'ada@example.com',
  first_name: 'Ada',
  last_name: 'Lovelace',
});
```

**Python**

```python
from emailit import EmailitClient
client = EmailitClient("your_api_key")

contact = client.contacts.create({
  "email": "ada@example.com",
  "first_name": "Ada",
  "last_name": "Lovelace",
})
```

**PHP**

```php
$emailit = Emailit::client('your_api_key');

$contact = $emailit->contacts()->create([
  'email' => 'ada@example.com',
  'first_name' => 'Ada',
  'last_name' => 'Lovelace',
]);
```

**Ruby**

```ruby
require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

contact = client.contacts.create(
  email: "ada@example.com",
  first_name: "Ada",
  last_name: "Lovelace"
)
```

**Go**

```go
import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

contact, err := client.Contacts.Create(&emailit.CreateContactRequest{
  Email:     "ada@example.com",
  FirstName: "Ada",
  LastName:  "Lovelace",
})
```

**Rust**

```rust
use emailit::Emailit;

let emailit = Emailit::new("your_api_key");

let contact = emailit.contacts.create(
  emailit::types::CreateContactParams::new("ada@example.com")
    .with_first_name("Ada")
    .with_last_name("Lovelace")
).await?;
```

**Java**

```java
import com.emailit.*;
import com.emailit.params.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject contact = emailit.contacts().create(
  ContactCreateParams.builder()
    .setEmail("ada@example.com")
    .setFirstName("Ada")
    .setLastName("Lovelace")
    .build()
);
```

**.NET**

```csharp
using Emailit;

var emailit = new EmailitClient("your_api_key");

var contact = emailit.Contacts.Create(new ContactCreateOptions {
  Email = "ada@example.com",
  FirstName = "Ada",
  LastName = "Lovelace",
});
```

**Laravel**

```php
use Emailit\Laravel\Facades\Emailit;

$contact = Emailit::contacts()->create([
  'email' => 'ada@example.com',
  'first_name' => 'Ada',
  'last_name' => 'Lovelace',
]);
```

**cURL**

```bash
curl -X POST https://api.emailit.com/v2/contacts \
  -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": "Analytical Engines", "plan": "pro" },
    "audiences": ["aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2"]
  }'
```

**201**

```json
{
  "object": "contact",
  "id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
  "email": "ada@example.com",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "custom_fields": {
    "company": "Analytical Engines",
    "plan": "pro"
  },
  "unsubscribed": false,
  "audiences": [
    {
      "id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
      "name": "Newsletter",
      "subscribed": true
    }
  ],
  "created_at": "2026-10-01T10:20:31.704113Z",
  "updated_at": "2026-10-01T10:20:31.704113Z"
}
```

**400**

```json
{
  "error": "Custom field \"Birthday\" must be a date in YYYY-MM-DD format"
}
```

**409**

```json
{
  "error": "Contact with this email already exists",
  "existing": {
    "object": "contact",
    "id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
    "email": "ada@example.com",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "custom_fields": {
      "company": "Analytical Engines",
      "plan": "pro"
    },
    "unsubscribed": false,
    "audiences": [
      {
        "id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
        "name": "Newsletter",
        "subscribed": true
      }
    ],
    "created_at": "2026-10-01T10:20:31.704113Z",
    "updated_at": "2026-10-01T10:20:31.704113Z"
  }
}
```

**422**

```json
{
  "error": "Pro includes 50,000 subscribers per audience.",
  "usage": {
    "used": 50000,
    "limit": 50000,
    "plan": "pro"
  }
}
```

---
Fonte: https://emailit.com/it/docs/api-reference/contacts/create/

## Recupera un contatto — GET /contacts/{id}

> Recupera un contatto tramite ID o indirizzo email, con i campi personalizzati e tutte le sue appartenenze alle liste, comprese le date di iscrizione.

# Recupera un contatto

Recupera un contatto con i campi personalizzati e le sue appartenenze alle liste.

`GET /contacts/{id}`

Richiede una chiave API `full`.

## Parametri di percorso

- `id` (string, obbligatorio): L’ID del contatto (`con_…`) o l’indirizzo email del contatto, codificato per l’URL.

## Restituisce

Restituisce l’oggetto contatto.

- `object` (string): Sempre `contact`.

- `id` (string): L’ID del contatto.

- `email` (string): L’indirizzo email, in minuscolo.

- `first_name` (string | null): Il nome.

- `last_name` (string | null): Il cognome.

- `custom_fields` (object): Valori dei campi personalizzati per chiave. `{}` quando non ce ne sono.

- `unsubscribed` (boolean): `true` se il contatto si è disiscritto da tutte le campagne.

- `audiences` (object[]): Le liste a cui appartiene il contatto, ciascuna con `id`, `name` e un oggetto `subscriber`: `id` (`sub_…`), `subscribed`, `subscribed_at`, `unsubscribed_at`, `created_at` e `updated_at`.

- `created_at` (string): Quando è stato creato il contatto.

- `updated_at` (string): Quando è stato modificato l’ultima volta il contatto.

**Richiesta** `GET /contacts/{id}`

**Node.js**

```javascript
import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const contact = await emailit.contacts.get('con_4K9kQdrXth7am0TPKvPrR5yd2oo');
```

**Python**

```python
from emailit import EmailitClient
client = EmailitClient("your_api_key")

contact = client.contacts.get("con_4K9kQdrXth7am0TPKvPrR5yd2oo")
```

**PHP**

```php
$emailit = Emailit::client('your_api_key');

$contact = $emailit->contacts()->get('con_4K9kQdrXth7am0TPKvPrR5yd2oo');
```

**Ruby**

```ruby
require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

contact = client.contacts.get("con_4K9kQdrXth7am0TPKvPrR5yd2oo")
```

**Go**

```go
import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

contact, err := client.Contacts.Get("con_4K9kQdrXth7am0TPKvPrR5yd2oo")
```

**Rust**

```rust
use emailit::Emailit;

let emailit = Emailit::new("your_api_key");

let contact = emailit.contacts.get("con_4K9kQdrXth7am0TPKvPrR5yd2oo").await?;
```

**Java**

```java
import com.emailit.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject contact = emailit.contacts().get("con_4K9kQdrXth7am0TPKvPrR5yd2oo");
```

**.NET**

```csharp
using Emailit;

var emailit = new EmailitClient("your_api_key");

var contact = emailit.Contacts.Get("con_4K9kQdrXth7am0TPKvPrR5yd2oo");
```

**Laravel**

```php
use Emailit\Laravel\Facades\Emailit;

$contact = Emailit::contacts()->get('con_4K9kQdrXth7am0TPKvPrR5yd2oo');
```

**cURL**

```bash
curl https://api.emailit.com/v2/contacts/con_4K9kQdrXth7am0TPKvPrR5yd2oo \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
```

**200**

```json
{
  "object": "contact",
  "id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
  "email": "ada@example.com",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "custom_fields": {
    "company": "Analytical Engines",
    "plan": "pro"
  },
  "unsubscribed": false,
  "audiences": [
    {
      "id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
      "name": "Newsletter",
      "subscriber": {
        "id": "sub_4KECYl5AwXEy8ezswYRhuddttxo",
        "subscribed": true,
        "subscribed_at": "2026-10-01T10:20:31.000000Z",
        "unsubscribed_at": null,
        "created_at": "2026-10-01T10:20:31.000000Z",
        "updated_at": "2026-10-01T10:20:31.000000Z"
      }
    }
  ],
  "created_at": "2026-10-01T10:20:31.000000Z",
  "updated_at": "2026-10-01T10:20:31.000000Z"
}
```

**404**

```json
{
  "error": "Contact not found"
}
```

---
Fonte: https://emailit.com/it/docs/api-reference/contacts/get/

## Aggiorna un contatto — POST /contacts/{id}

> Modifica l’indirizzo email, i nomi, i campi personalizzati o lo stato di disiscrizione di un contatto, oppure sostituisci le liste a cui appartiene.

# Aggiorna un contatto

Aggiorna un contatto. Cambiano solo i campi che invii.

`POST /contacts/{id}`

Richiede una chiave API `full`. Genera `contact.updated`, con i valori precedenti dei campi modificati in `previous`. La modifica di `audiences` genera anche `subscriber.created` e `subscriber.deleted` per le appartenenze alle liste che aggiunge e rimuove.

## Parametri di percorso

- `id` (string, obbligatorio): L’ID del contatto (`con_…`) o l’indirizzo email del contatto, codificato per l’URL.

## Parametri del corpo

- `email` (string): Un nuovo indirizzo email. Non deve appartenere a un altro contatto.

- `first_name` (string): Il nome.

- `last_name` (string): Il cognome.

- `custom_fields` (object): Valori dei campi personalizzati per chiave. Sostituisce tutti i campi personalizzati del contatto, quindi includi quelli che vuoi mantenere.

- `unsubscribed` (boolean): `true` per disiscrivere il contatto da tutte le campagne, `false` per reiscriverlo. Le appartenenze alle liste esistenti mantengono il proprio stato.

- `audiences` (string[]): L’elenco completo degli ID delle liste a cui il contatto deve appartenere. Il contatto viene aggiunto alle liste di cui non fa ancora parte e rimosso da quelle che non sono nel tuo elenco. Invia `[]` per rimuoverlo da tutte le liste. Per aggiungere o rimuovere una sola lista senza elencarle tutte, usa [Aggiungi un iscritto](/it/docs/api-reference/audiences/subscribers/add/) o [Elimina un iscritto](/it/docs/api-reference/audiences/subscribers/delete/).

## Restituisce

Restituisce il contatto aggiornato nello stesso formato di [Recupera un contatto](/it/docs/api-reference/contacts/get/). Una richiesta senza nessuno di questi campi restituisce `400`.

**Richiesta** `POST /contacts/{id}`

**Node.js**

```javascript
import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const contact = await emailit.contacts.update('con_4K9kQdrXth7am0TPKvPrR5yd2oo', {
  first_name: 'Augusta',
});
```

**Python**

```python
from emailit import EmailitClient
client = EmailitClient("your_api_key")

contact = client.contacts.update("con_4K9kQdrXth7am0TPKvPrR5yd2oo", {
  "first_name": "Augusta",
})
```

**PHP**

```php
$emailit = Emailit::client('your_api_key');

$contact = $emailit->contacts()->update('con_4K9kQdrXth7am0TPKvPrR5yd2oo', [
  'first_name' => 'Augusta',
]);
```

**Ruby**

```ruby
require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

contact = client.contacts.update("con_4K9kQdrXth7am0TPKvPrR5yd2oo",
  first_name: "Augusta"
)
```

**Go**

```go
import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

contact, err := client.Contacts.Update("con_4K9kQdrXth7am0TPKvPrR5yd2oo", &emailit.UpdateContactRequest{
  FirstName: "Augusta",
})
```

**Rust**

```rust
use emailit::Emailit;

let emailit = Emailit::new("your_api_key");

let contact = emailit.contacts.update("con_4K9kQdrXth7am0TPKvPrR5yd2oo",
  emailit::types::UpdateContactParams {
    first_name: Some("Augusta".into()),
    ..Default::default()
  }
).await?;
```

**Java**

```java
import com.emailit.*;
import com.emailit.params.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject contact = emailit.contacts().update("con_4K9kQdrXth7am0TPKvPrR5yd2oo", 
  ContactUpdateParams.builder()
    .setFirstName("Augusta")
    .build()
);
```

**.NET**

```csharp
using Emailit;

var emailit = new EmailitClient("your_api_key");

var contact = emailit.Contacts.Update("con_4K9kQdrXth7am0TPKvPrR5yd2oo", new ContactUpdateOptions {
  FirstName = "Augusta",
});
```

**Laravel**

```php
use Emailit\Laravel\Facades\Emailit;

$contact = Emailit::contacts()->update('con_4K9kQdrXth7am0TPKvPrR5yd2oo', [
  'first_name' => 'Augusta',
]);
```

**cURL**

```bash
curl -X POST https://api.emailit.com/v2/contacts/con_4K9kQdrXth7am0TPKvPrR5yd2oo \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"first_name": "Augusta"}'
```

**cURL**

```bash
curl -X POST https://api.emailit.com/v2/contacts/ada%40example.com \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "custom_fields": { "company": "Analytical Engines", "plan": "business" },
    "audiences": ["aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "aud_4KOlh9t2uw5od4qypqCtyrZyDq2"]
  }'
```

**200**

```json
{
  "object": "contact",
  "id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
  "email": "ada@example.com",
  "first_name": "Augusta",
  "last_name": "Lovelace",
  "custom_fields": {
    "company": "Analytical Engines",
    "plan": "pro"
  },
  "unsubscribed": false,
  "audiences": [
    {
      "id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
      "name": "Newsletter",
      "subscriber": {
        "id": "sub_4KECYl5AwXEy8ezswYRhuddttxo",
        "subscribed": true,
        "subscribed_at": "2026-10-01T10:20:31.000000Z",
        "unsubscribed_at": null,
        "created_at": "2026-10-01T10:20:31.000000Z",
        "updated_at": "2026-10-01T10:20:31.000000Z"
      }
    }
  ],
  "created_at": "2026-10-01T10:20:31.000000Z",
  "updated_at": "2026-10-02T09:03:17.000000Z"
}
```

**400**

```json
{
  "error": "No valid fields provided for update. Provide at least one of: email, first_name, last_name, custom_fields, unsubscribed, audiences"
}
```

**404**

```json
{
  "error": "Contact not found"
}
```

**409**

```json
{
  "error": "Another contact with this email already exists"
}
```

---
Fonte: https://emailit.com/it/docs/api-reference/contacts/update/

## Elenca i contatti — GET /contacts

> Elenca i contatti di un workspace, a partire dal più recente, filtrati per lista, stato dell’iscrizione, campi personalizzati o qualsiasi campo del contatto.

# Elenca i contatti

Restituisce una pagina di contatti, a partire dal più recente.

`GET /contacts`

Richiede una chiave API `full`. Usa gli stessi parametri con [Esporta i contatti](/it/docs/api-reference/contacts/export/) per scaricare tutti i risultati come file.

## Parametri di query

- `page` (integer): La pagina da restituire.

- `limit` (integer): Contatti per pagina, da 1 a 100.

- `search` (string): Corrispondenza sull’indirizzo email, sul nome o sul cognome, senza distinzione tra maiuscole e minuscole. Funziona anche `q`.

- `audience_id` (string): Solo i contatti di questa lista (`aud_…`).

- `unsubscribed` (boolean): `true` o `false`. Solo i contatti con questo stato di disiscrizione.

- `sort` (string): `email`, `first_name`, `last_name`, `name`, `audiences`, `created_at` o `updated_at`.

- `order` (string): `asc` o `desc`. In questo endpoint `order` è la direzione dell’ordinamento, non la chiave di ordinamento.

- `match` (string): `all` o `or`. Come si combinano i filtri qui sotto.

## Filtri

Aggiungi i filtri nella forma `key.condition=value`, ad esempio `email.ends_with=@acme.com` o `custom_fields.plan.exact=pro`. Vedi [Filtri e ordinamento](/it/docs/api-reference/filtering/).

| Chiave | Tipo | Note |
| --- | --- | --- |
| `email` | string | |
| `first_name` | string | |
| `last_name` | string | |
| `name` | string | Nome e cognome uniti da uno spazio. |
| `audiences` | string | Il primo nome di lista del contatto in ordine alfabetico. |
| `unsubscribed` | boolean | |
| `created_at` | date | |
| `updated_at` | date | |
| `audience_id` | string | Solo `exact` e `not_exact`. Il valore è l’ID di una lista. |
| `custom_fields.<key>` | string | Sostituisci `<key>` con la chiave di un campo personalizzato. I valori vengono confrontati come testo. |

I parametri precedenti `filter[audience_id]`, `filter[unsubscribed]` e `filter[custom_fields][<key>]` funzionano ancora.

## Restituisce

- `data` (object[]): I contatti di questa pagina, ciascuno con `audiences` come `id`, `name` e `subscribed`. Vedi [Recupera un contatto](/it/docs/api-reference/contacts/get/).

- `total_records` (integer): Il numero di contatti corrispondenti, su tutte le pagine.

- `next_page_url` (string | null): Percorso della pagina successiva con i tuoi filtri, oppure `null`. Vedi [Paginazione](/it/docs/api-reference/pagination/).

- `previous_page_url` (string | null): Percorso della pagina precedente, oppure `null`.

**Richiesta** `GET /contacts`

**Node.js**

```javascript
import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const contacts = await emailit.contacts.list();
```

**Python**

```python
from emailit import EmailitClient
client = EmailitClient("your_api_key")

contacts = client.contacts.list()
```

**PHP**

```php
$emailit = Emailit::client('your_api_key');

$contacts = $emailit->contacts()->list();
```

**Ruby**

```ruby
require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

contacts = client.contacts.list
```

**Go**

```go
import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

contacts, err := client.Contacts.List(nil)
```

**Rust**

```rust
use emailit::Emailit;

let emailit = Emailit::new("your_api_key");

let contacts = emailit.contacts.list(None).await?;
```

**Java**

```java
import com.emailit.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject contacts = emailit.contacts().list();
```

**.NET**

```csharp
using Emailit;

var emailit = new EmailitClient("your_api_key");

var contacts = emailit.Contacts.List();
```

**Laravel**

```php
use Emailit\Laravel\Facades\Emailit;

$contacts = Emailit::contacts()->list();
```

**cURL**

```bash
curl https://api.emailit.com/v2/contacts \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
```

**cURL**

```bash
curl -G https://api.emailit.com/v2/contacts \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  --data-urlencode "audience_id=aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2" \
  --data-urlencode "custom_fields.plan.exact=pro" \
  --data-urlencode "sort=email" \
  --data-urlencode "order=asc" \
  --data-urlencode "limit=100"
```

**200**

```json
{
  "data": [
    {
      "object": "contact",
      "id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
      "email": "ada@example.com",
      "first_name": "Ada",
      "last_name": "Lovelace",
      "custom_fields": {
        "company": "Analytical Engines",
        "plan": "pro"
      },
      "unsubscribed": false,
      "audiences": [
        {
          "id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
          "name": "Newsletter",
          "subscribed": true
        }
      ],
      "created_at": "2026-10-01T10:20:31.704113Z",
      "updated_at": "2026-10-01T10:20:31.704113Z"
    },
    {
      "object": "contact",
      "id": "con_4KiXIs4xLTcJIAHnKJaLcnMZYh7",
      "email": "grace@example.com",
      "first_name": "Grace",
      "last_name": "Hopper",
      "custom_fields": {},
      "unsubscribed": true,
      "audiences": [],
      "created_at": "2026-09-28T07:55:02.118342Z",
      "updated_at": "2026-09-30T18:11:40.902215Z"
    }
  ],
  "total_records": 2,
  "next_page_url": null,
  "previous_page_url": null
}
```

---
Fonte: https://emailit.com/it/docs/api-reference/contacts/list/

## Aggiorna i contatti in blocco — POST /contacts/bulk

> Applica un’azione a un massimo di 100 contatti alla volta: eliminali, aggiungili a una lista o rimuovili, disiscrivili o reiscrivili.

# Aggiorna i contatti in blocco

Esegue un’azione su un massimo di 100 contatti in una sola richiesta.

`POST /contacts/bulk`

Richiede una chiave API `full`. Ogni ID deve appartenere a un contatto del workspace, altrimenti non viene modificato nulla e la risposta elenca gli ID mancanti in `missing`. Ogni contatto genera gli stessi eventi degli endpoint per i singoli contatti. Se durante `add_to_audience` la lista raggiunge il limite di iscritti del piano, la richiesta si interrompe con `422` e i contatti elaborati fino a quel momento restano aggiunti.

| Azione | Cosa fa |
| --- | --- |
| `delete` | Elimina i contatti e la loro appartenenza alle liste, come [Elimina un contatto](/it/docs/api-reference/contacts/delete/). |
| `add_to_audience` | Aggiunge i contatti a `audience_id`. I contatti che ne fanno già parte restano come sono. |
| `remove_from_audience` | Rimuove i contatti da `audience_id`. |
| `unsubscribe` | Imposta `unsubscribed` su `true`, così le campagne saltano i contatti. |
| `resubscribe` | Imposta `unsubscribed` su `false`. |

## Parametri del corpo

- `action` (string, obbligatorio): `delete`, `add_to_audience`, `remove_from_audience`, `unsubscribe` o `resubscribe`.

- `ids` (string[], obbligatorio): ID dei contatti (`con_…`), da 1 a 100. Qui gli indirizzi email non sono accettati. I duplicati vengono ignorati.

- `audience_id` (string): L’ID della lista. Obbligatorio per `add_to_audience` e `remove_from_audience`.

## Restituisce

- `object` (string): Sempre `contact_bulk`.

- `action` (string): L’azione eseguita.

- `processed` (integer): Quanti contatti sono stati elaborati.

- `ids` (string[]): Gli ID dei contatti elaborati.

**Richiesta** `POST /contacts/bulk`

**Node.js**

```javascript
const response = await fetch('https://api.emailit.com/v2/contacts/bulk', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"action": "add_to_audience", "ids": ["con_4K9kQdrXth7am0TPKvPrR5yd2oo", "con_4KiXIs4xLTcJIAHnKJaLcnMZYh7"], "audience_id": "aud_4KOlh9t2uw5od4qypqCtyrZyDq2"}),
});
const result = await response.json();
```

**Python**

```python
import requests

response = requests.post(
  "https://api.emailit.com/v2/contacts/bulk",
  headers={"Authorization": "Bearer your_api_key"},
  json={"action": "add_to_audience", "ids": ["con_4K9kQdrXth7am0TPKvPrR5yd2oo", "con_4KiXIs4xLTcJIAHnKJaLcnMZYh7"], "audience_id": "aud_4KOlh9t2uw5od4qypqCtyrZyDq2"}
)
result = response.json()
```

**PHP**

```php
$ch = curl_init('https://api.emailit.com/v2/contacts/bulk');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer your_api_key',
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode(['action' => 'add_to_audience', 'ids' => ['con_4K9kQdrXth7am0TPKvPrR5yd2oo', 'con_4KiXIs4xLTcJIAHnKJaLcnMZYh7'], 'audience_id' => 'aud_4KOlh9t2uw5od4qypqCtyrZyDq2']),
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
```

**Ruby**

```ruby
require "net/http"
require "json"

uri = URI("https://api.emailit.com/v2/contacts/bulk")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer your_api_key"
req["Content-Type"] = "application/json"
req.body = { action: "add_to_audience", ids: ["con_4K9kQdrXth7am0TPKvPrR5yd2oo", "con_4KiXIs4xLTcJIAHnKJaLcnMZYh7"], audience_id: "aud_4KOlh9t2uw5od4qypqCtyrZyDq2" }.to_json
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
result = JSON.parse(http.request(req).body)
```

**Go**

```go
payload := strings.NewReader(`{"action": "add_to_audience", "ids": ["con_4K9kQdrXth7am0TPKvPrR5yd2oo", "con_4KiXIs4xLTcJIAHnKJaLcnMZYh7"], "audience_id": "aud_4KOlh9t2uw5od4qypqCtyrZyDq2"}`)
req, _ := http.NewRequest("POST", "https://api.emailit.com/v2/contacts/bulk", payload)
req.Header.Set("Authorization", "Bearer your_api_key")
req.Header.Set("Content-Type", "application/json")

resp, err := http.DefaultClient.Do(req)
if err != nil {
  return err
}
defer resp.Body.Close()
```

**Rust**

```rust
let response = reqwest::Client::new()
    .post("https://api.emailit.com/v2/contacts/bulk")
    .bearer_auth("your_api_key")
    .json(&serde_json::json!({"action": "add_to_audience", "ids": ["con_4K9kQdrXth7am0TPKvPrR5yd2oo", "con_4KiXIs4xLTcJIAHnKJaLcnMZYh7"], "audience_id": "aud_4KOlh9t2uw5od4qypqCtyrZyDq2"}))
    .send()
    .await?;
```

**Java**

```java
import java.net.http.*;
import java.net.URI;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
  .uri(URI.create("https://api.emailit.com/v2/contacts/bulk"))
  .header("Authorization", "Bearer your_api_key")
  .header("Content-Type", "application/json")
  .POST(HttpRequest.BodyPublishers.ofString("{\"action\": \"add_to_audience\", \"ids\": [\"con_4K9kQdrXth7am0TPKvPrR5yd2oo\", \"con_4KiXIs4xLTcJIAHnKJaLcnMZYh7\"], \"audience_id\": \"aud_4KOlh9t2uw5od4qypqCtyrZyDq2\"}"))
  .build();
HttpResponse<String> response = client.send(request,
  HttpResponse.BodyHandlers.ofString());
```

**.NET**

```csharp
using System.Net.Http.Headers;
using System.Text;

var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "your_api_key");

var content = new StringContent(@"{""action"": ""add_to_audience"", ""ids"": [""con_4K9kQdrXth7am0TPKvPrR5yd2oo"", ""con_4KiXIs4xLTcJIAHnKJaLcnMZYh7""], ""audience_id"": ""aud_4KOlh9t2uw5od4qypqCtyrZyDq2""}", Encoding.UTF8, "application/json");
var response = await http.PostAsync("https://api.emailit.com/v2/contacts/bulk", content);
```

**Laravel**

```php
use Illuminate\Support\Facades\Http;

$result = Http::withToken('your_api_key')
  ->post('https://api.emailit.com/v2/contacts/bulk', ['action' => 'add_to_audience', 'ids' => ['con_4K9kQdrXth7am0TPKvPrR5yd2oo', 'con_4KiXIs4xLTcJIAHnKJaLcnMZYh7'], 'audience_id' => 'aud_4KOlh9t2uw5od4qypqCtyrZyDq2'])
  ->json();
```

**cURL**

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

**200**

```json
{
  "object": "contact_bulk",
  "action": "add_to_audience",
  "processed": 2,
  "ids": ["con_4K9kQdrXth7am0TPKvPrR5yd2oo", "con_4KiXIs4xLTcJIAHnKJaLcnMZYh7"]
}
```

**400**

```json
{
  "error": "A maximum of 100 contacts can be updated per request"
}
```

**404**

```json
{
  "error": "One or more contacts were not found",
  "missing": ["con_4K3pZc1Q9nWm2LrT8vYb5Hd0XaE"]
}
```

**422**

```json
{
  "error": "Pro includes 50,000 subscribers per audience.",
  "usage": {
    "used": 50000,
    "limit": 50000,
    "plan": "pro"
  }
}
```

---
Fonte: https://emailit.com/it/docs/api-reference/contacts/bulk/

## Esporta i contatti — GET /contacts/export

> Scarica i contatti che corrispondono ai filtri come file CSV o Excel, con le loro liste e i campi personalizzati. Fino a 10.000 contatti.

# Esporta i contatti

Scarica i contatti corrispondenti come file CSV o XLSX.

`GET /contacts/export`

Richiede una chiave API `full`. Accetta gli stessi parametri di ricerca, filtro e ordinamento di [Elenca i contatti](/it/docs/api-reference/contacts/list/), passati nella query string, senza paginazione. `POST /contacts/export` funziona allo stesso modo. Un’esportazione può includere fino a 10.000 contatti; se ne corrispondono di più, la richiesta restituisce `422`, quindi restringi i filtri.

## Parametri di query

- `format` (string): `csv` o `xlsx`.

- `search, audience_id, unsubscribed, sort, order, match, key.condition` (string): Gli stessi parametri di [Elenca i contatti](/it/docs/api-reference/contacts/list/).

## Restituisce

Restituisce il file come allegato: `contacts.csv` (`text/csv; charset=utf-8`) o `contacts.xlsx`. Ogni riga è un contatto con queste colonne:

| Colonna | Contenuto |
| --- | --- |
| `email` | L’indirizzo email. |
| `first_name`, `last_name` | Il nome e il cognome. |
| `unsubscribed` | `true` o `false`. |
| `audiences` | I nomi delle liste del contatto, separati da `; `. |
| Una colonna per ogni campo personalizzato | Il valore di ogni campo personalizzato definito nel workspace, con la sua chiave come nome. I valori di tipo elenco sono uniti con `;`. |
| `created_at`, `updated_at` | Timestamp ISO 8601. |

**Richiesta** `GET /contacts/export`

**Node.js**

```javascript
import { writeFile } from 'node:fs/promises';

const response = await fetch('https://api.emailit.com/v2/contacts/export?format=csv&audience_id=aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', {
  headers: { Authorization: 'Bearer your_api_key' },
});
await writeFile('contacts.csv', Buffer.from(await response.arrayBuffer()));
```

**Python**

```python
import requests

response = requests.get(
  "https://api.emailit.com/v2/contacts/export?format=csv&audience_id=aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
  headers={"Authorization": "Bearer your_api_key"}
)
with open("contacts.csv", "wb") as f:
    f.write(response.content)
```

**PHP**

```php
$ch = curl_init('https://api.emailit.com/v2/contacts/export?format=csv&audience_id=aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer your_api_key',
  ],
]);
file_put_contents('contacts.csv', curl_exec($ch));
curl_close($ch);
```

**Ruby**

```ruby
require "net/http"

uri = URI("https://api.emailit.com/v2/contacts/export?format=csv&audience_id=aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer your_api_key"
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
File.binwrite("contacts.csv", http.request(req).body)
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.emailit.com/v2/contacts/export?format=csv&audience_id=aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", nil)
req.Header.Set("Authorization", "Bearer your_api_key")

resp, err := http.DefaultClient.Do(req)
if err != nil {
  return err
}
defer resp.Body.Close()

out, _ := os.Create("contacts.csv")
defer out.Close()
io.Copy(out, resp.Body)
```

**Rust**

```rust
let bytes = reqwest::Client::new()
    .get("https://api.emailit.com/v2/contacts/export?format=csv&audience_id=aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2")
    .bearer_auth("your_api_key")
    .send()
    .await?
    .bytes()
    .await?;
std::fs::write("contacts.csv", &bytes)?;
```

**Java**

```java
import java.net.http.*;
import java.net.URI;
import java.nio.file.Path;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
  .uri(URI.create("https://api.emailit.com/v2/contacts/export?format=csv&audience_id=aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2"))
  .header("Authorization", "Bearer your_api_key")
  .GET()
  .build();
client.send(request, HttpResponse.BodyHandlers.ofFile(Path.of("contacts.csv")));
```

**.NET**

```csharp
using System.Net.Http.Headers;

var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "your_api_key");

var bytes = await http.GetByteArrayAsync("https://api.emailit.com/v2/contacts/export?format=csv&audience_id=aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2");
await File.WriteAllBytesAsync("contacts.csv", bytes);
```

**Laravel**

```php
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Storage;

$csv = Http::withToken('your_api_key')
  ->get('https://api.emailit.com/v2/contacts/export?format=csv&audience_id=aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2')
  ->body();
Storage::put('contacts.csv', $csv);
```

**cURL**

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

**200**

```text
email,first_name,last_name,unsubscribed,audiences,company,plan,created_at,updated_at
ada@example.com,Ada,Lovelace,false,Newsletter,Analytical Engines,pro,2026-10-01T10:20:31.000000Z,2026-10-01T10:20:31.000000Z
```

**400**

```json
{
  "error": "format must be csv or xlsx"
}
```

**422**

```json
{
  "error": "Export is limited to 10000 contacts. Narrow your filters and try again."
}
```

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

## Elimina un contatto — DELETE /contacts/{id}

> Elimina definitivamente un contatto e rimuovilo da tutte le liste. Le email già inviate al contatto restano nei log.

# Elimina un contatto

Elimina definitivamente un contatto e tutte le sue appartenenze alle liste.

`DELETE /contacts/{id}`

Richiede una chiave API `full`. L’eliminazione non si può annullare. Per smettere di inviare email a qualcuno ma conservarne i dati, [aggiorna il contatto](/it/docs/api-reference/contacts/update/) con `unsubscribed: true`, oppure aggiungi l’indirizzo alle [soppressioni](/it/docs/api-reference/suppressions/create/). Genera un `subscriber.deleted` per ogni appartenenza a una lista, poi `contact.deleted`.

## Parametri di percorso

- `id` (string, obbligatorio): L’ID del contatto (`con_…`) o l’indirizzo email del contatto, codificato per l’URL.

## Restituisce

- `object` (string): Sempre `contact`.

- `id` (string): L’ID del contatto eliminato.

- `email` (string): L’indirizzo email del contatto.

- `deleted` (boolean): Sempre `true`.

**Richiesta** `DELETE /contacts/{id}`

**Node.js**

```javascript
import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

await emailit.contacts.delete('con_4Kt4ZXloQR8WGcMsYx8PFCUjokM');
```

**Python**

```python
from emailit import EmailitClient
client = EmailitClient("your_api_key")

client.contacts.delete("con_4Kt4ZXloQR8WGcMsYx8PFCUjokM")
```

**PHP**

```php
$emailit = Emailit::client('your_api_key');

$emailit->contacts()->delete('con_4Kt4ZXloQR8WGcMsYx8PFCUjokM');
```

**Ruby**

```ruby
require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

client.contacts.delete("con_4Kt4ZXloQR8WGcMsYx8PFCUjokM")
```

**Go**

```go
import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

err := client.Contacts.Delete("con_4Kt4ZXloQR8WGcMsYx8PFCUjokM")
```

**Rust**

```rust
use emailit::Emailit;

let emailit = Emailit::new("your_api_key");

emailit.contacts.delete("con_4Kt4ZXloQR8WGcMsYx8PFCUjokM").await?;
```

**Java**

```java
import com.emailit.*;

EmailitClient emailit = new EmailitClient("your_api_key");

emailit.contacts().delete("con_4Kt4ZXloQR8WGcMsYx8PFCUjokM");
```

**.NET**

```csharp
using Emailit;

var emailit = new EmailitClient("your_api_key");

emailit.Contacts.Delete("con_4Kt4ZXloQR8WGcMsYx8PFCUjokM");
```

**Laravel**

```php
use Emailit\Laravel\Facades\Emailit;

Emailit::contacts()->delete('con_4Kt4ZXloQR8WGcMsYx8PFCUjokM');
```

**cURL**

```bash
curl -X DELETE https://api.emailit.com/v2/contacts/con_4Kt4ZXloQR8WGcMsYx8PFCUjokM \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
```

**200**

```json
{
  "object": "contact",
  "id": "con_4Kt4ZXloQR8WGcMsYx8PFCUjokM",
  "email": "alan@example.com",
  "deleted": true
}
```

**404**

```json
{
  "error": "Contact not found"
}
```

---
Fonte: https://emailit.com/it/docs/api-reference/contacts/delete/