Contatti

Gestisci i contatti in Contatti > Tutti i contatti nella dashboard, con bird contacts dal terminale, tramite l'API dei contatti o con uno qualsiasi degli SDK.

Raggiungere i contatti

Per inviare un'email a una persona, usa il suo indirizzo con l'API di invio; il record del contatto conserva le sue informazioni, pronte per essere riutilizzate. Per raggiungere più persone insieme, invia un lotto oppure raggruppale in un pubblico e invia un broadcast. Memorizzare un contatto non invia nulla di per sé.

La pagina Contatti

La pagina Contatti mostra il nome del contatto, gli identificativi, i pubblici a cui appartiene e le informazioni di creazione. Cerca per nome, email o telefono, poi seleziona una riga per aprire il contatto. Usa le azioni nell'intestazione per aggiungere un contatto o importarne molti. La visualizzazione richiede il permesso di lettura email_marketing. L'aggiunta, la modifica e l'eliminazione richiedono il permesso di scrittura.

Cosa contiene un contatto

Ogni contatto ha un indirizzo email, un numero di telefono o entrambi, ciascuno univoco nel tuo spazio di lavoro, più un nome e un tuo identificativo facoltativi:

Campo	Descrizione
email	L'indirizzo, univoco nel tuo spazio di lavoro. Lo memorizziamo in minuscolo, senza spazi iniziali o finali, quindi Sam@Acme.com e sam@acme.com vengono normalizzati allo stesso identificativo.
phone_number	Il numero di telefono, univoco nel tuo spazio di lavoro. Il formato viene normalizzato a quello internazionale. La memorizzazione non verifica i metadati del piano di numerazione, la titolarità, la raggiungibilità o il consenso.
first_name	Nome proprio facoltativo, usato per personalizzare un invio.
last_name	Cognome facoltativo.
external_id	Facoltativo. La tua chiave primaria per la persona (un ID utente del tuo database), univoca nel tuo spazio di lavoro quando impostata. Ti permette di collegare un contatto ai tuoi record senza dipendere dall'email.
data	Valori delle proprietà personalizzate, uno per ogni proprietà di contatto registrata.

La dashboard ricava le etichette Email e SMS dagli identificativi presenti. L'API restituisce email e phone_number; non restituisce un campo channels. Queste etichette non attestano il permesso di invio o la raggiungibilità sul canale.

Ogni contatto ha anche un ID con prefisso con_ e i timestamp di creazione e aggiornamento. La specifica completa dei campi si trova nel riferimento API.

Proprietà di contatto

Le proprietà di contatto definiscono lo schema tipizzato dei campi personalizzati di un contatto. Registra una proprietà per il tuo spazio di lavoro: da quel momento ogni contatto potrà avere un valore per quella proprietà in data. Dichiarare lo schema in anticipo rende affidabili la personalizzazione e la segmentazione: un valore arriva sempre con il tipo dichiarato, su cui un modello o un filtro può quindi fare affidamento.

Gestiscile in Contatti > Proprietà di contatto. Ogni proprietà ha una chiave, un tipo e un valore di ripiego facoltativo:

La chiave è il nome con cui fai riferimento al valore, per esempio plan_tier. Deve essere in minuscolo e iniziare con una lettera (^[a-z][a-z0-9_]*$), e non può essere modificata dopo la creazione.
Il tipo è uno tra string, number, boolean e datetime, e anch'esso non può essere modificato dopo la creazione. Un datetime accetta un timestamp RFC 3339 con un offset esplicito, come 2026-01-15T11:30:00+02:00, che normalizziamo in UTC con precisione al secondo. Il valore viene quindi memorizzato e restituito come 2026-01-15T09:30:00Z. Una data senza ora viene rifiutata. Nella dashboard questi tipi sono indicati come Testo, Numero, Vero / falso e Data e ora.
Il valore di ripiego è quello letto per un contatto privo di un valore proprio: se manca plan_tier, può quindi essere restituito free invece di un valore vuoto.

Le proprietà vengono archiviate anziché eliminate. L'archiviazione impedisce nuove scritture sulla chiave, ma conserva tutti i valori già memorizzati. La chiave resta riservata e non potrà mai essere riutilizzata con un tipo diverso. Ripristina la proprietà dall'archivio per riattivarla. Questa riserva spiega anche perché il tipo è immutabile: un number memorizzato non deve mai iniziare a essere letto come uno string. Uno spazio di lavoro può registrare fino a 200 proprietà; quelle archiviate contano nel limite perché le loro chiavi restano riservate.

Imposta i valori delle proprietà dove modifichi un contatto. Il modulo del contatto nella dashboard mostra un campo di input tipizzato per ogni proprietà attiva, e la CLI e l'API accettano le stesse chiavi in data.

Importare e sincronizzare i contatti

Per importare un elenco dalla pagina Contatti, seleziona Importa e carica un file CSV, TSV o Excel. Inserisci un contatto per riga e una riga di intestazione con i nomi delle colonne. Un file può contenere fino a 50.000 contatti. I file CSV possono avere dimensioni fino a 50 MB, mentre i fogli di calcolo possono arrivare a 10 MB.

La riga di intestazione aiuta a identificare ogni campo del contatto. Le colonne chiamate "Email Address", "E-Mail" o "Correo electrónico" vengono tutte associate al campo email. Una singola colonna contenente il nome completo viene suddivisa in nome e cognome. Se due colonne possono compilare lo stesso campo, viene scelta quella i cui valori confermano il nome. Ogni colonna mostra alcuni dei propri valori per rendere visibile il contenuto, e un nome suddiviso viene mostrato accanto al valore originale. Puoi cambiare queste associazioni dal menu a discesa di ogni colonna. Tutte le persone nel file possono essere aggiunte a uno o più pubblici durante la stessa importazione.

Ogni riga viene abbinata a un contatto esistente tramite gli identificativi che contiene e lo aggiorna, oppure crea un nuovo contatto. Reimportare lo stesso file esegue quindi un upsert anziché accumulare duplicati. Prima di scrivere qualsiasi dato, la dashboard indica quante righe iniziali non possono essere importate con la mappatura corrente. Dopo l'esecuzione, ogni riga ignorata riporta il numero di riga nel file di origine e l'errore.

Per sincronizzare dal tuo database, automatizza la CLI con uno script o chiama l'endpoint per i lotti. bird contacts create <email> aggiunge un contatto. bird contacts batch crea o aggiorna fino a 1.000 contatti con una sola chiamata. Usa un lotto per esecuzione invece di una richiesta per persona per mantenere l'elenco dei contatti sincronizzato con il tuo sistema.

const contact = await bird.contacts.create({
  email: "jane@acme.com",
  first_name: "Jane",
});
console.log(contact.id); // "con_…"

contact = client.contacts.create(email="jane@acme.com", first_name="Jane")
print(contact.id, contact.email)

contact, err := client.Contacts.Create(context.Background(), bird.ContactCreateParams{
	Email:     bird.Ptr("jane@acme.com"),
	FirstName: bird.Ptr("Jane"),
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(contact.Id)

$contact = $bird->contacts->create(
    (new ContactCreateRequest())
        ->setEmail('jane@acme.com')
        ->setFirstName('Jane'),
);
echo $contact->getId(); // "con_…"

bird contacts create alice@acme.com \
  --first-name Alice \
  --last-name Anderson \
  --phone-number +31612345678

{
  "name": "contacts_create",
  "arguments": {
    "email": "alice@acme.com",
    "first_name": "Alice",
    "last_name": "Anderson",
    "phone_number": "+31612345678"
  }
}

curl -X POST "https://{region}.platform.bird.com/v1/contacts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@acme.com",
    "phone_number": "+31612345678",
    "first_name": "Alice",
    "last_name": "Anderson"
  }'

Ogni voce del lotto viene abbinata automaticamente in base agli identificativi forniti (indirizzo email, numero di telefono o ID esterno). Il campo facoltativo match_on impone invece di cercare la corrispondenza su uno solo di questi identificativi. Una voce può anche impostare valori di proprietà personalizzate e aggiungere direttamente tutti i contatti della richiesta ai pubblici tramite audience_ids. Ogni voce riesce o fallisce indipendentemente, e la risposta riporta un risultato per voce nell'ordine di invio:

Esempio di codice

{
  "data": [
    {
      "contact_id": "con_01ky7q5t51echr7mqj5c08423b",
      "entry": { "email": "alex@example.com", "phone_number": null, "external_id": null },
      "matched_on": "email",
      "status": "updated"
    },
    {
      "contact_id": "con_01ky7q6mxdfhe86c9dqyt866pz",
      "entry": { "email": "jamie@example.com", "phone_number": null, "external_id": null },
      "matched_on": null,
      "status": "created"
    },
    {
      "contact_id": "con_01ky7q7rv9e9pt4vkr0w0gxq5e",
      "entry": { "email": "casey@example.com", "phone_number": null, "external_id": "user_2214" },
      "matched_on": "external_id",
      "status": "updated"
    }
  ]
}

Se gli identificativi di una voce rimandano a contatti esistenti diversi, la voce fallisce con un conflitto da esaminare. Risolvi il record di origine prima di riprovare; il lotto non unisce quei contatti.

Due comportamenti predefiniti sono utili per una sincronizzazione. Un lotto unisce le chiavi data ai dati esistenti del contatto, quindi un'importazione che modifica un attributo non cancella mai gli altri. Invia un valore null per cancellare una chiave, oppure imposta data_mode: "replace" per sovrascrivere l'intera mappa. Imposta un tuo external_id su ogni contatto, in modo che una sincronizzazione successiva trovi la stessa persona anche dopo una modifica dell'email. Nell'esempio del lotto, user_2214 esiste già, quindi la voce viene abbinata a quel contatto e sostituisce l'email con quella nuova.

Eliminare un contatto

L'eliminazione di un contatto è permanente: il record e le sue appartenenze ai pubblici vengono rimossi e non possono essere recuperati. Soppressioni e preferenze restano però invariate. Un indirizzo che ha generato un hard bounce rimane nella tua lista di soppressione, e uno che si è disiscritto conserva la preferenza di non ricevere messaggi anche dopo l'eliminazione del contatto. Eliminare qualcuno non riabilita quindi mai silenziosamente l'invio al suo indirizzo.

Passaggi successivi

Pubblici: raggruppa i contatti in elenchi riutilizzabili
Soppressioni: l'elenco degli indirizzi nello spazio di lavoro a cui non consegniamo messaggi, separato dai tuoi contatti
Invio in lotti: raggiungi più destinatari con una sola chiamata, fino a 100 messaggi per richiesta
CLI: automatizza contatti, proprietà e pubblici tramite script con il comando bird
Riferimento API: gli schemi completi di richieste e risposte

Risorse correlate

Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.

Guarda la guidaGetting started with email Esplora la funzionalitàEmail Segui il percorso di apprendimentoBuild your first integration Guida all'implementazioneSend your first email

Prova l'esercitazione e ottieni un brief di implementazione