Contacten

Beheer contacten in het dashboard onder Contacts > All contacts, vanuit de terminal met bird contacts, via de contacten-API of met een van de SDK's.

Contacten bereiken

Om één persoon te e-mailen, verstuur je naar diens adres met de verzend-API. Het contactrecord bewaart de gegevens van die persoon voor hergebruik. Om veel mensen tegelijk te bereiken, verstuur je een batch of groepeer je hen in een doelgroep en verstuur je een broadcast. Een contact opslaan verstuurt op zichzelf niets.

De pagina Contacts

De pagina Contacts toont de naam, identificatiegegevens, doelgroeplidmaatschappen en aanmaakgegevens van het contact. Zoek op naam, e-mailadres of telefoonnummer en selecteer een rij om het contact te openen. Gebruik de acties bovenaan om één contact toe te voegen of meerdere contacten te importeren. Bekijken vereist leesrechten voor email_marketing. Toevoegen, bewerken en verwijderen vereisen schrijfrechten.

Wat een contact bevat

Elk contact heeft een e-mailadres, een telefoonnummer of beide, elk uniek binnen je werkruimte. Daarnaast kun je een naam en een eigen identificatiecode opgeven:

Veld	Betekenis
email	Het adres, uniek binnen je werkruimte. We verwijderen witruimte aan het begin en einde en slaan het in kleine letters op. Daardoor worden Sam@Acme.com en sam@acme.com genormaliseerd naar hetzelfde identificatiegegeven.
phone_number	Het telefoonnummer, uniek binnen je werkruimte. De opmaak wordt genormaliseerd naar de internationale vorm. Opslag controleert geen metadata van het nummerplan, eigendom, bereikbaarheid of toestemming.
first_name	Optionele voornaam, gebruikt om een verzending te personaliseren.
last_name	Optionele achternaam.
external_id	Optioneel. Je eigen primaire sleutel voor de persoon, bijvoorbeeld een gebruikers-ID uit je database. Als deze is ingesteld, is hij uniek binnen je werkruimte. Hiermee koppel je een contact aan je eigen records zonder afhankelijk te zijn van het e-mailadres.
data	Waarden van aangepaste eigenschappen, één per geregistreerde contacteigenschap.

Het dashboard leidt de labels Email en SMS af van de aanwezige identificatiegegevens. De API retourneert email en phone_number, maar geen veld channels. Die labels bewijzen geen toestemming om te verzenden of bereikbaarheid via het kanaal.

Elk contact heeft ook een ID met het voorvoegsel con_ en tijdstempels voor aanmaak en bijwerking. De volledige veldspecificatie staat in de API-referentie.

Contacteigenschappen

Contacteigenschappen vormen het typeschema voor de aangepaste velden van een contact. Registreer een eigenschap voor je werkruimte. Vanaf dat moment kan elk contact er een waarde voor hebben onder data. Door het schema vooraf vast te leggen, maak je personalisatie en segmentatie betrouwbaar: een waarde heeft altijd het opgegeven type, waarop een template of filter kan rekenen.

De pagina Contact properties in het dashboard, met zes eigenschappen en hun sleutel, type, terugvalwaarde en aanmaakdatum, waarvan één met het label Archived

Beheer ze onder Contacts > Contact properties. Elke eigenschap heeft een sleutel, een type en een optionele terugvalwaarde:

De sleutel is de naam waarmee je naar de waarde verwijst, bijvoorbeeld plan_tier. Deze moet in kleine letters staan en met een letter beginnen (^[a-z][a-z0-9_]*$). Na het aanmaken kun je de sleutel niet wijzigen.
Het type is string, number, boolean of datetime en staat na het aanmaken ook vast. Een datetime accepteert een RFC 3339-tijdstempel met een expliciete tijdzone-offset, zoals 2026-01-15T11:30:00+02:00. We normaliseren die naar UTC met een nauwkeurigheid van seconden, zodat die waarde wordt opgeslagen en geretourneerd als 2026-01-15T09:30:00Z. Een losse datum zonder tijd wordt afgewezen. Het dashboard noemt deze typen Text, Number, True / false en Date & time.
De terugvalwaarde wordt uitgelezen voor een contact zonder eigen waarde. Daardoor kan een ontbrekende plan_tier als free verschijnen in plaats van als een leeg veld.

Eigenschappen worden gearchiveerd in plaats van verwijderd. Archiveren voorkomt nieuwe schrijfacties naar de sleutel en bewaart alle al opgeslagen waarden. De sleutel blijft gereserveerd, zodat die nooit met een ander type kan terugkomen. Hef de archivering op om de eigenschap weer te gebruiken. Die reservering is ook de reden waarom het type onveranderlijk is: een opgeslagen number mag nooit ineens als string worden uitgelezen. Een werkruimte kan maximaal 200 eigenschappen registreren. Gearchiveerde eigenschappen tellen mee voor die limiet, omdat hun sleutels gereserveerd blijven.

Stel eigenschapswaarden in waar je een contact bewerkt. Het contactformulier in het dashboard toont per actieve eigenschap een invoerveld met het juiste type. De CLI en de API accepteren dezelfde sleutels onder data.

Contacten importeren en synchroniseren

Om een lijst vanaf de pagina Contacts te importeren, selecteer je Import en upload je een CSV-, TSV- of Excel-bestand. Gebruik één contact per rij en een koprij met de kolomnamen. Een bestand mag maximaal 50.000 contacten bevatten. CSV-bestanden mogen maximaal 50 MB groot zijn en spreadsheetbestanden maximaal 10 MB.

De koprij helpt elk contactveld te herkennen. Kolommen met de naam "Email Address", "E-Mail" of "Correo electrónico" worden allemaal aan het e-mailveld gekoppeld. Eén kolom met een volledige naam wordt gesplitst in een voornaam en een achternaam. Als twee kolommen hetzelfde veld kunnen vullen, krijgt de kolom waarvan de waarden de naam bevestigen voorrang. Elke kolom toont enkele eigen waarden, zodat je ziet wat erin staat. Een opgesplitste naam wordt naast de oorspronkelijke waarde getoond. Je kunt dit aanpassen via het keuzemenu van elke kolom. Iedereen in het bestand kan tijdens dezelfde import aan één of meer doelgroepen worden toegevoegd.

Elke rij wordt op basis van de aanwezige identificatiegegevens gekoppeld aan een bestaand contact en bijgewerkt, of aangemaakt als het een nieuw contact is. Hetzelfde bestand opnieuw importeren voert dus een upsert uit en levert geen stapel duplicaten op. Voordat er iets wordt opgeslagen, meldt het dashboard hoeveel van de aanvankelijk gecontroleerde rijen met de huidige koppeling niet kunnen worden geïmporteerd. Na de uitvoering toont elke overgeslagen rij het oorspronkelijke regelnummer en de fout.

Om vanuit je eigen database te synchroniseren, gebruik je een script voor de CLI of roep je het batch-endpoint aan. bird contacts create <email> voegt één contact toe. bird contacts batch maakt maximaal 1.000 contacten aan of werkt ze bij met één aanroep. Gebruik één batch per uitvoering in plaats van één verzoek per persoon om je contactenlijst gelijk te houden aan je systeem.

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

Elke batchinvoer wordt automatisch gekoppeld op basis van de meegegeven identificatiegegevens: e-mailadres, telefoonnummer of externe ID. Het optionele veld match_on dwingt in plaats daarvan een koppeling op precies één daarvan af. Een invoer kan ook waarden voor aangepaste eigenschappen instellen. Via audience_ids kunnen alle contacten in het verzoek rechtstreeks aan doelgroepen worden toegevoegd. Elke invoer slaagt of mislukt onafhankelijk. Het antwoord geeft één resultaat per invoer, in de volgorde van indiening:

Codevoorbeeld

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

Als de identificatiegegevens van een invoer naar verschillende bestaande contacten verwijzen, mislukt die invoer met een conflict dat je moet controleren. Corrigeer het bronrecord voordat je het opnieuw probeert. De batch voegt die contacten niet samen.

Twee standaardgedragingen zijn handig bij synchronisatie. Een batch voegt sleutels onder data samen met bestaande contactgegevens. Een import die één eigenschap aanpast, wist daardoor nooit de andere. Stuur de waarde null om één sleutel leeg te maken of stel data_mode: "replace" in om de hele map te overschrijven. Stel je eigen external_id in voor elk contact, zodat een latere synchronisatie dezelfde persoon vindt, ook na een gewijzigd e-mailadres. In het batchvoorbeeld bestaat user_2214 al. De invoer wordt dus aan dat contact gekoppeld en vervangt het e-mailadres door het nieuwe.

Een contact verwijderen

Een contact verwijderen is definitief: het record en de doelgroeplidmaatschappen verdwijnen en kunnen niet worden hersteld. Suppressies en voorkeuren blijven wel behouden. Een adres met een hard bounce blijft op je suppressielijst, en een adres dat zich heeft uitgeschreven behoudt zijn opt-outvoorkeur nadat je het contact verwijdert. Iemand verwijderen zorgt er dus nooit ongemerkt voor dat je die persoon weer kunt e-mailen.

Vervolgstappen

Doelgroepen: groepeer contacten in herbruikbare lijsten
Suppressies: de lijst met adressen in de werkruimte waar we geen berichten bezorgen, afzonderlijk van je contacten
Batchverzending: bereik veel ontvangers met één aanroep, met maximaal 100 berichten per verzoek
CLI: beheer contacten, eigenschappen en doelgroepen via scripts met de opdracht bird
API-referentie: volledige verzoek- en antwoordschema's

Gerelateerde bronnen

Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.

Bekijk de gidsGetting started with email Ontdek de mogelijkheidEmail Volg het leerpadBuild your first integration ImplementatiegidsSend your first email

Probeer de oefening en ontvang een implementatieoverzicht