Contatti

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

URL di basehttps://api.emailit.com/v2Autenticazione Errori Limiti di frequenza

POST/contacts
GET/contacts/{id}
POST/contacts/{id}
GET/contacts
POST/contacts/bulk
POST/contacts/{id}/tags
DEL/contacts/{id}/tags
GET/contacts/tags
POST/contacts/{id}/score
GET/contacts/export
DEL/contacts/{id}

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.

Parametri del corpo

emailstringobbligatorio

L’indirizzo email del contatto.

first_namestring

Il nome.

last_namestring

Il cognome.

custom_fieldsobject

Valori per chiave del campo personalizzato, 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.

audiencesstring[]

ID delle liste (aud_…) a cui iscrivere il contatto. Gli ID che non esistono nel workspace vengono saltati.

tagsstring[]

Fino a 50 tag, salvati in minuscolo.

scoreintegerpredefinito: 0

Il lead score iniziale del contatto.

unsubscribedbooleanpredefinito: false

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.

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

POST/contacts

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

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

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

PHP

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

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

Ruby

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

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

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

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

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()
);

using Emailit;

var emailit = new EmailitClient("your_api_key");

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

PHP

use Emailit\Laravel\Facades\Emailit;

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

Terminal

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

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

JSON

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

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

JSON

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

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

idstringobbligatorio

L’ID del contatto (con_…) o l’indirizzo email del contatto, codificato per l’URL.

Restituisce

Restituisce l’oggetto contatto.

objectstring

Sempre contact.

idstring

L’ID del contatto.

emailstring

L’indirizzo email, in minuscolo.

first_namestring | null

Il nome.

last_namestring | null

Il cognome.

custom_fieldsobject

Valori dei campi personalizzati per chiave. {} quando non ce ne sono.

unsubscribedboolean

true se il contatto si è disiscritto da tutte le campagne.

tagsstring[]

I tag del contatto, in minuscolo e in ordine.

scoreinteger

Il lead score del contatto.

audiencesobject[]

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_atstring

Quando è stato creato il contatto.

updated_atstring

Quando è stato modificato l’ultima volta il contatto.

GET/contacts/{id}

JavaScript

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

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

Python

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

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

PHP

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

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

Ruby

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

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

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

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

Rust

use emailit::Emailit;

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

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

Java

import com.emailit.*;

EmailitClient emailit = new EmailitClient("your_api_key");

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

using Emailit;

var emailit = new EmailitClient("your_api_key");

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

PHP

use Emailit\Laravel\Facades\Emailit;

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

Terminal

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

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

JSON

{
  "error": "Contact not found"
}

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

idstringobbligatorio

L’ID del contatto (con_…) o l’indirizzo email del contatto, codificato per l’URL.

Parametri del corpo

emailstring

Un nuovo indirizzo email. Non deve appartenere a un altro contatto.

first_namestring

Il nome.

last_namestring

Il cognome.

custom_fieldsobject

Valori dei campi personalizzati per chiave. Sostituisce tutti i campi personalizzati del contatto, quindi includi quelli che vuoi mantenere.

unsubscribedboolean

true per disiscrivere il contatto da tutte le campagne, false per reiscriverlo. Le appartenenze alle liste esistenti mantengono il proprio stato.

tagsstring[]

Sostituisce tutti i tag del contatto. [] li rimuove tutti.

add_tagsstring[]

Tag da aggiungere, mantenendo gli altri.

remove_tagsstring[]

Tag da rimuovere.

scoreinteger

Imposta il lead score. Per aggiungere o sottrarre punti, usa Modifica il lead score di un contatto.

audiencesstring[]

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 o Elimina un iscritto.

Restituisce

Restituisce il contatto aggiornato nello stesso formato di Recupera un contatto. Una richiesta senza nessuno di questi campi restituisce 400.

POST/contacts/{id}

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

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

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

PHP

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

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

Ruby

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

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

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

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

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()
);

using Emailit;

var emailit = new EmailitClient("your_api_key");

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

PHP

use Emailit\Laravel\Facades\Emailit;

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

Terminal

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

Terminal

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

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

JSON

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

JSON

{
  "error": "Contact not found"
}

JSON

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

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 per scaricare tutti i risultati come file.

Parametri di query

pageintegerpredefinito: 1

La pagina da restituire.

limitintegerpredefinito: 10

Contatti per pagina, da 1 a 100.

searchstring

Corrispondenza sull’indirizzo email, sul nome o sul cognome, senza distinzione tra maiuscole e minuscole. Funziona anche q.

audience_idstring

Solo i contatti di questa lista (aud_…).

unsubscribedboolean

true o false. Solo i contatti con questo stato di disiscrizione.

filter[tag]string

Solo i contatti con questo tag. Separa più tag con una virgola per i contatti che ne hanno almeno uno. Funziona anche tag.

filter[score][gte], filter[score][lte]integer

Solo i contatti con un lead score almeno pari o al massimo pari a questo valore.

sortstringpredefinito: created_at

email, first_name, last_name, name, audiences, score, created_at o updated_at.

orderstringpredefinito: desc

asc o desc. In questo endpoint order è la direzione dell’ordinamento, non la chiave di ordinamento.

matchstringpredefinito: all

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.

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

dataobject[]

I contatti di questa pagina, ciascuno con audiences come id, name e subscribed. Vedi Recupera un contatto.

total_recordsinteger

Il numero di contatti corrispondenti, su tutte le pagine.

next_page_urlstring | null

Percorso della pagina successiva con i tuoi filtri, oppure null. Vedi Paginazione.

previous_page_urlstring | null

Percorso della pagina precedente, oppure null.

GET/contacts

JavaScript

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

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

Python

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

contacts = client.contacts.list()

PHP

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

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

Ruby

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

contacts = client.contacts.list

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

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

Rust

use emailit::Emailit;

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

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

Java

import com.emailit.*;

EmailitClient emailit = new EmailitClient("your_api_key");

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

using Emailit;

var emailit = new EmailitClient("your_api_key");

var contacts = emailit.Contacts.List();

PHP

use Emailit\Laravel\Facades\Emailit;

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

Terminal

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

Terminal

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"

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
}

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

actionstringobbligatorio

delete, add_to_audience, remove_from_audience, unsubscribe o resubscribe.

idsstring[]obbligatorio

ID dei contatti (con_…), da 1 a 100. Qui gli indirizzi email non sono accettati. I duplicati vengono ignorati.

audience_idstring

L’ID della lista. Obbligatorio per add_to_audience e remove_from_audience.

Restituisce

objectstring

Sempre contact_bulk.

actionstring

L’azione eseguita.

processedinteger

Quanti contatti sono stati elaborati.

idsstring[]

Gli ID dei contatti elaborati.

POST/contacts/bulk

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

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

$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

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)

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

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

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());

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);

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();

Terminal

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

JSON

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

JSON

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

JSON

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

JSON

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

Aggiungi tag a un contatto

Aggiunge tag a un contatto. I tag che il contatto ha già restano invariati. Richiede una chiave API con il permesso full.

I tag vengono ripuliti dagli spazi iniziali e finali e salvati in minuscolo, con gli spazi consecutivi ridotti a uno, e possono avere fino a 64 caratteri. Quando almeno un tag è nuovo, Emailit genera un evento contact.updated con i nuovi tags e quelli precedenti in previous.tags, che avvia le automazioni Tag added. Vedi Tag e lead score.

POST/contacts/{id}/tags

Parametri di percorso

idstringobbligatorio

L’ID del contatto (con_…) o l’indirizzo email del contatto, codificato per l’URL.

Parametri del corpo

tagsstring[]obbligatorio

I tag da aggiungere, fino a 50.

Restituisce

dataobject

id ed email del contatto, tutti i suoi tags dopo la modifica, e changed, i tag che sono stati aggiunti.

messagestring

Ad esempio 1 tag added. o No tags changed.

Restituisce 400 quando un tag è vuoto o supera i 64 caratteri, e 404 se il contatto non esiste.

JSON

{
  "data": {
    "id": "con_2kq8Vt4xLm7Rz",
    "email": "ada@example.com",
    "tags": ["customer", "vip", "webinar-2026"],
    "changed": ["customer", "webinar-2026"]
  },
  "message": "2 tags added."
}

POST/contacts/{id}/tags

Terminal

curl -X POST https://api.emailit.com/v2/contacts/ada@example.com/tags \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tags": ["customer", "webinar-2026"]}'

JavaScript

const res = await fetch('https://api.emailit.com/v2/contacts/ada@example.com/tags', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({"tags": ["customer", "webinar-2026"]}),
});
const result = await res.json();

Python

import os, requests

r = requests.post(
    "https://api.emailit.com/v2/contacts/ada@example.com/tags",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
    json={"tags": ["customer", "webinar-2026"]},
)
result = r.json()

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->post('contacts/ada@example.com/tags', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
    'json' => ['tags' => ['customer', 'webinar-2026']],
]);
$result = json_decode($response->getBody(), true);

Rimuovi tag da un contatto

Rimuove tag da un contatto. I tag che il contatto non ha vengono ignorati. Richiede una chiave API con il permesso full.

Quando viene rimosso almeno un tag, Emailit genera un evento contact.updated con previous.tags, che avvia le automazioni Tag removed. Vedi Tag e lead score.

DELETE/contacts/{id}/tags

Parametri di percorso

idstringobbligatorio

L’ID del contatto (con_…) o l’indirizzo email del contatto, codificato per l’URL.

Parametri del corpo

tagsstring[]obbligatorio

I tag da rimuovere, fino a 50. Il confronto avviene in minuscolo.

Restituisce

dataobject

id ed email del contatto, i tags rimasti, e changed, i tag che sono stati rimossi.

messagestring

Ad esempio 1 tag removed. o No tags changed.

Restituisce 404 se il contatto non esiste.

DELETE/contacts/{id}/tags

Terminal

curl -X DELETE https://api.emailit.com/v2/contacts/con_2kq8Vt4xLm7Rz/tags \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tags": ["trial"]}'

JavaScript

const res = await fetch('https://api.emailit.com/v2/contacts/con_2kq8Vt4xLm7Rz/tags', {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({"tags": ["trial"]}),
});
const result = await res.json();

Python

import os, requests

r = requests.delete(
    "https://api.emailit.com/v2/contacts/con_2kq8Vt4xLm7Rz/tags",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
    json={"tags": ["trial"]},
)
result = r.json()

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->delete('contacts/con_2kq8Vt4xLm7Rz/tags', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
    'json' => ['tags' => ['trial']],
]);
$result = json_decode($response->getBody(), true);

Restituisce i tag usati sui contatti del workspace, in ordine alfabetico, con il numero di contatti che ha ciascun tag. Richiede una chiave API con il permesso full. Per elencare i contatti con un tag, usa Elenca i contatti con filter[tag].

GET/contacts/tags

Parametri di query

searchstring

Solo i tag che contengono questo testo.

limitintegerpredefinito: 200

Quanti tag restituire, da 1 a 1000.

Restituisce

dataobject[]

Ogni tag nella forma { "object": "tag", "tag": "customer", "contacts": 42 }.

GET/contacts/tags

Terminal

curl "https://api.emailit.com/v2/contacts/tags?search=web" \
  -H "Authorization: Bearer $EMAILIT_API_KEY"

JavaScript

const res = await fetch('https://api.emailit.com/v2/contacts/tags?search=web', {
  method: 'GET',
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` },
});
const result = await res.json();

Python

import os, requests

r = requests.get(
    "https://api.emailit.com/v2/contacts/tags?search=web",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
)
result = r.json()

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->get('contacts/tags?search=web', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
]);
$result = json_decode($response->getBody(), true);

Modifica il lead score di un contatto

Aggiunge punti al lead score di un contatto, li sottrae oppure imposta il punteggio. Richiede una chiave API con il permesso full.

La modifica è atomica, quindi le chiamate in parallelo non si sovrascrivono a vicenda. Il punteggio parte da 0, può essere negativo e resta entro ±1.000.000.000. Quando il punteggio cambia, Emailit genera un evento contact.updated con score e previous.score, che avvia le automazioni Score changed. Vedi Tag e lead score.

POST/contacts/{id}/score

Parametri di percorso

idstringobbligatorio

L’ID del contatto (con_…) o l’indirizzo email del contatto, codificato per l’URL.

Parametri del corpo

operationstringpredefinito: add

add, subtract o set.

valueintegerobbligatorio

I punti da aggiungere o sottrarre, oppure il nuovo punteggio.

Restituisce

dataobject

id ed email del contatto, il nuovo score e il previous_score.

messagestring

Ad esempio Score is now 55.

Restituisce 400 quando operation o value non è valido, e 404 se il contatto non esiste.

JSON

{
  "data": { "id": "con_2kq8Vt4xLm7Rz", "email": "ada@example.com", "score": 55, "previous_score": 45 },
  "message": "Score is now 55."
}

POST/contacts/{id}/score

Terminal

curl -X POST https://api.emailit.com/v2/contacts/con_2kq8Vt4xLm7Rz/score \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"operation": "add", "value": 10}'

JavaScript

const res = await fetch('https://api.emailit.com/v2/contacts/con_2kq8Vt4xLm7Rz/score', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({"operation": "add", "value": 10}),
});
const result = await res.json();

Python

import os, requests

r = requests.post(
    "https://api.emailit.com/v2/contacts/con_2kq8Vt4xLm7Rz/score",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
    json={"operation": "add", "value": 10},
)
result = r.json()

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->post('contacts/con_2kq8Vt4xLm7Rz/score', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
    'json' => ['operation' => 'add', 'value' => 10],
]);
$result = json_decode($response->getBody(), true);

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, 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

formatstringpredefinito: csv

csv o xlsx.

search, audience_id, unsubscribed, sort, order, match, key.conditionstring

Gli stessi parametri di Elenca i contatti.

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 `;` .
`tags`	I tag del contatto, separati da `;` .
`score`	Il lead score.
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.

GET/contacts/export

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

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

$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

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)

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

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

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")));

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);

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);

Terminal

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

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

JSON

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

JSON

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

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 con unsubscribed: true, oppure aggiungi l’indirizzo alle soppressioni. Genera un subscriber.deleted per ogni appartenenza a una lista, poi contact.deleted.

Parametri di percorso

idstringobbligatorio

L’ID del contatto (con_…) o l’indirizzo email del contatto, codificato per l’URL.

Restituisce

objectstring

Sempre contact.

idstring

L’ID del contatto eliminato.

emailstring

L’indirizzo email del contatto.

deletedboolean

Sempre true.

DELETE/contacts/{id}

JavaScript

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

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

Python

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

client.contacts.delete("con_4Kt4ZXloQR8WGcMsYx8PFCUjokM")

PHP

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

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

Ruby

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

client.contacts.delete("con_4Kt4ZXloQR8WGcMsYx8PFCUjokM")

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

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

Rust

use emailit::Emailit;

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

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

Java

import com.emailit.*;

EmailitClient emailit = new EmailitClient("your_api_key");

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

using Emailit;

var emailit = new EmailitClient("your_api_key");

emailit.Contacts.Delete("con_4Kt4ZXloQR8WGcMsYx8PFCUjokM");

PHP

use Emailit\Laravel\Facades\Emailit;

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

Terminal

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

JSON

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

JSON

{
  "error": "Contact not found"
}

Crea un contatto

Parametri del corpo

Restituisce

Recupera un contatto

Parametri di percorso

Restituisce

Aggiorna un contatto

Parametri di percorso

Parametri del corpo

Restituisce

Elenca i contatti

Parametri di query

Filtri

Restituisce

Aggiorna i contatti in blocco

Parametri del corpo

Restituisce

Aggiungi tag a un contatto

Parametri di percorso

Parametri del corpo

Restituisce

Rimuovi tag da un contatto

Parametri di percorso

Parametri del corpo

Restituisce

Elenca i tag

Parametri di query

Restituisce

Modifica il lead score di un contatto

Parametri di percorso

Parametri del corpo

Restituisce

Esporta i contatti

Parametri di query

Restituisce

Elimina un contatto

Parametri di percorso

Restituisce