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:

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.

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.

Archiviare una proprietà

L’archiviazione è il modo per rimuovere una proprietà di contatto. Bird conserva i suoi valori, così puoi ripristinarla con Annulla archiviazione. Non è prevista l’eliminazione definitiva di una proprietà.

Una proprietà archiviata scompare dai selettori delle proprietà, anche durante la mappatura delle colonne di importazione. Le nuove versioni di template che la leggono non possono essere pubblicate. L’errore di pubblicazione indica la proprietà. I template già pubblicati continuano a inviare e usano il valore del contatto o il valore di ripiego della proprietà.

I contatti conservano i valori memorizzati. Puoi ancora leggerli e aggiornarli tramite l’API e le importazioni. I valori devono corrispondere al tipo della proprietà.

Se un’automazione pubblicata, anche in pausa, usa la proprietà in un trigger o nella scrittura di dati di contatto, l’archiviazione restituisce un conflitto 409. Anche un’esecuzione attiva che scrive la proprietà impedisce l’archiviazione. Rimuovi la proprietà da queste automazioni o archiviale. Lascia terminare le esecuzioni attive o annullale, quindi archivia di nuovo la proprietà. L’errore indica le automazioni se hai il permesso di leggerle.

Annulla l’archiviazione della proprietà per ripristinarla con i suoi valori. Apparirà di nuovo nei selettori e potrà essere usata nelle nuove versioni di template. La sua chiave resta riservata mentre è archiviata e conta nel limite di 200 proprietà del workspace.

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.

Il conteggio dei duplicati dell'importazione si riferisce a righe ripetute all'interno del file. Usa l'indirizzo email quando presente, altrimenti il numero di telefono. Le corrispondenze con contatti già presenti nel tuo spazio di lavoro appaiono come aggiornamenti quando API li conferma.

“This row was not confirmed as saved” significa che la dashboard non ha ricevuto un risultato che conferma quella riga. La riga potrebbe essere stata salvata, anche se i conteggi di creazione e aggiornamento sono zero. Controlla alcuni contatti interessati prima di riprovare. Tieni aperta la scheda di importazione fino al termine; la dashboard esegue l'importazione da quella scheda.

Per sincronizzare dal tuo database, usa lo script CLI o chiama il batch endpoint. bird contacts create <email> ne aggiunge uno. bird contacts batch esegue l'upsert di un massimo di 1.000 contatti in una singola chiamata. Usa un batch per esecuzione anziché una richiesta per persona, per mantenere la lista contatti allineata 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

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 batch viene abbinata automaticamente in base agli identificatori forniti (indirizzo email, numero di telefono o ID esterno), e il campo opzionale match_on forza l'abbinamento su uno solo di essi. Una voce può anche impostare valori di proprietà personalizzate e inserire ogni contatto della richiesta direttamente nelle audience tramite audience_ids. Ogni voce ha esito positivo o negativo in modo indipendente, e la risposta riporta un risultato per voce nell'ordine di invio:

{
  "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 identificatori di una voce puntano a contatti esistenti diversi, la voce fallisce con un conflitto da esaminare. Correggi il record di origine prima di riprovare; il batch non unisce quei contatti.

Due impostazioni predefinite sono utili per una sincronizzazione. Un batch unisce le chiavi data ai dati del contatto esistente, quindi un'importazione che tocca un solo attributo non cancella gli altri. Invia un valore null per svuotare una chiave, oppure imposta data_mode: "replace" per sovrascrivere l'intera mappa. Imposta il tuo external_id su ogni contatto, così una sincronizzazione successiva trova la stessa persona anche dopo che il suo indirizzo email cambia. Nell'esempio del batch, user_2214 esiste già, quindi la voce viene risolta su quel contatto e scrive il nuovo indirizzo email al suo posto.

Eliminazione di un contatto

L'eliminazione di un contatto è permanente: il record e le sue appartenenze alle audience vengono rimossi, e nulla li recupera. Le soppressioni e le preferenze restano intatte, però. Un indirizzo che ha generato un hard bounce rimane nella tua lista di soppressione, e uno che ha annullato l'iscrizione conserva la propria preferenza di opt-out, anche dopo che elimini il contatto, quindi eliminare qualcuno non lo rende di nuovo raggiungibile in modo silenzioso.

Passi successivi

• Audience: raggruppa i contatti in liste riutilizzabili
• Soppressioni: la lista dello spazio di lavoro degli indirizzi a cui non consegniamo, tenuta separata dai tuoi contatti
• Invio batch: raggiungi molti destinatari in una sola chiamata, fino a 100 messaggi per richiesta
• CLI: gestione di contatti, proprietà e audience tramite il comando bird
• API reference: schemi completi di richiesta e risposta