Kontakte

Verwalten Sie Kontakte im Dashboard unter Contacts > All contacts, im Terminal mit bird contacts, über die Kontakte-API oder mit einem der SDKs.

Kontakte erreichen

Um einer Person eine E-Mail zu senden, verwenden Sie ihre Adresse mit der Versand-API. Der Kontaktdatensatz speichert ihre Informationen zur späteren Wiederverwendung. Um viele Personen gleichzeitig zu erreichen, senden Sie einen Batch oder fassen Sie sie in einer Zielgruppe zusammen und senden Sie einen Broadcast. Das Speichern eines Kontakts allein löst keinen Versand aus.

Die Seite Contacts

Die Seite Contacts zeigt Namen, Kennungen, Zielgruppenmitgliedschaften und Erstellungsinformationen des Kontakts. Suchen Sie nach Namen, E-Mail-Adresse oder Telefonnummer und wählen Sie eine Zeile aus, um den Kontakt zu öffnen. Über die Aktionen im Kopfbereich können Sie einen Kontakt hinzufügen oder mehrere importieren. Zum Anzeigen benötigen Sie die Leseberechtigung für email_marketing. Zum Hinzufügen, Bearbeiten und Löschen ist die Schreibberechtigung erforderlich.

Welche Daten ein Kontakt enthält

Jeder Kontakt hat eine E-Mail-Adresse, eine Telefonnummer oder beides. Jede Kennung ist in Ihrem Workspace eindeutig. Optional können Sie einen Namen und eine eigene Kennung hinterlegen:

Das Dashboard leitet die Labels Email und SMS aus den vorhandenen Kennungen ab. Die API gibt email und phone_number zurück, jedoch kein Feld channels. Diese Labels belegen weder eine Versandberechtigung noch die Erreichbarkeit über den Kanal.

Jeder Kontakt hat außerdem eine ID mit dem Präfix con_ sowie Zeitstempel für Erstellung und Aktualisierung. Die vollständige Feldspezifikation finden Sie in der API-Referenz.

Kontakteigenschaften

Kontakteigenschaften bilden das typisierte Schema für die benutzerdefinierten Felder eines Kontakts. Registrieren Sie eine Eigenschaft für Ihren Workspace. Danach kann jeder Kontakt unter data einen Wert dafür haben. Das vorab deklarierte Schema macht Personalisierung und Segmentierung zuverlässig: Ein Wert hat immer den deklarierten Typ, auf den sich ein Template oder Filter verlassen kann.

Verwalten Sie sie unter Contacts > Contact properties. Jede Eigenschaft hat einen Schlüssel, einen Typ und einen optionalen Ersatzwert:

• Der Schlüssel ist der Name, unter dem Sie den Wert referenzieren, zum Beispiel plan_tier. Er muss kleingeschrieben sein und mit einem Buchstaben beginnen (^[a-z][a-z0-9_]*$). Nach dem Erstellen lässt er sich nicht mehr ändern.
• Der Typ ist string, number, boolean oder datetime und lässt sich nach dem Erstellen ebenfalls nicht ändern. Ein Wert vom Typ datetime akzeptiert einen RFC-3339-Zeitstempel mit explizitem Offset, etwa 2026-01-15T11:30:00+02:00. Wir normalisieren ihn sekundengenau auf UTC, sodass dieser Wert als 2026-01-15T09:30:00Z gespeichert und zurückgegeben wird. Ein Datum ohne Uhrzeit wird abgelehnt. Das Dashboard bezeichnet diese Typen als Text, Number, True / false und Date & time.
• Der Ersatzwert wird für einen Kontakt ohne eigenen Wert gelesen. Ein fehlender Wert für plan_tier kann so als free statt als leeres Feld erscheinen.

Legen Sie Eigenschaftswerte dort fest, wo Sie einen Kontakt bearbeiten. Das Kontaktformular im Dashboard zeigt pro aktiver Eigenschaft ein typisiertes Eingabefeld. Die CLI und die API akzeptieren dieselben Schlüssel unter data.

Eine Eigenschaft archivieren

Durch Archivieren entfernen Sie eine Kontakteigenschaft. Bird behält ihre Werte, damit Sie sie mit Dearchivieren wiederherstellen können. Eine Eigenschaft kann nicht endgültig gelöscht werden.

Eine archivierte Eigenschaft verschwindet aus der Eigenschaftsauswahl, auch bei der Zuordnung von Importspalten. Neue Template-Versionen, die sie lesen, können nicht veröffentlicht werden. Die Fehlermeldung nennt die Eigenschaft. Bereits veröffentlichte Templates senden weiter und verwenden den Wert des Kontakts oder den Ersatzwert der Eigenschaft.

Kontakte behalten ihre gespeicherten Werte. Sie können diese weiterhin über die API und Importe lesen und aktualisieren. Die Werte müssen dem Typ der Eigenschaft entsprechen.

Wenn eine veröffentlichte Automation, einschließlich einer pausierten, die Eigenschaft in einem Trigger oder beim Schreiben von Kontaktdaten verwendet, gibt das Archivieren einen 409-Konflikt zurück. Ein aktiver Lauf, der die Eigenschaft schreibt, verhindert das Archivieren ebenfalls. Entfernen Sie die Eigenschaft aus diesen Automationen oder archivieren Sie diese. Lassen Sie aktive Läufe fertig werden oder brechen Sie sie ab. Archivieren Sie die Eigenschaft danach erneut. Die Fehlermeldung nennt die Automationen, wenn Sie sie lesen dürfen.

Dearchivieren Sie die Eigenschaft, um sie mit ihren Werten wiederherzustellen. Sie erscheint wieder in der Auswahl und kann in neuen Template-Versionen verwendet werden. Ihr Schlüssel bleibt während der Archivierung reserviert und zählt zum Limit von 200 Eigenschaften pro Workspace.

Kontakte importieren und synchronisieren

Um auf der Seite Contacts eine Liste zu importieren, wählen Sie Import und laden Sie eine CSV-, TSV- oder Excel-Datei hoch. Verwenden Sie eine Zeile pro Kontakt und eine Kopfzeile mit den Spaltennamen. Eine Datei darf bis zu 50.000 Kontakte enthalten. CSV-Dateien dürfen bis zu 50 MB, Tabellendateien bis zu 10 MB groß sein.

Die Kopfzeile hilft dabei, die Kontaktfelder zu erkennen. Spalten mit den Namen "Email Address", "E-Mail" oder "Correo electrónico" werden alle dem E-Mail-Feld zugeordnet. Eine einzelne Spalte mit einem vollständigen Namen wird in Vor- und Nachnamen aufgeteilt. Wenn zwei Spalten dasselbe Feld ausfüllen könnten, wird diejenige gewählt, deren Werte zu ihrem Namen passen. Jede Spalte zeigt einige Beispielwerte, damit Sie ihren Inhalt erkennen. Bei aufgeteilten Namen wird der ursprüngliche Wert zum Vergleich angezeigt. Über das Dropdown-Menü jeder Spalte können Sie die Zuordnung ändern. Alle Personen in der Datei können beim selben Import zu einer oder mehreren Zielgruppen hinzugefügt werden.

Jede Zeile wird anhand ihrer Kennungen einem bestehenden Kontakt zugeordnet und aktualisiert oder als neuer Kontakt angelegt. Ein erneuter Import derselben Datei führt somit einen Upsert durch und erzeugt keine Duplikate. Bevor etwas gespeichert wird, zeigt das Dashboard an, wie viele der anfänglich geprüften Zeilen mit der aktuellen Zuordnung nicht importiert werden können. Nach dem Durchlauf werden für jede übersprungene Zeile die ursprüngliche Zeilennummer und der Fehler angezeigt.

Die Duplikat-Anzahl des Imports bezieht sich auf wiederholte Zeilen innerhalb Ihrer Datei. Sie verwendet die E-Mail-Adresse, wenn vorhanden, oder andernfalls die Telefonnummer. Übereinstimmungen mit bereits in Ihrem Workspace vorhandenen Kontakten erscheinen als Aktualisierungen, wenn API sie bestätigt.

“This row was not confirmed as saved” bedeutet, dass das Dashboard kein Ergebnis erhalten hat, das diese Zeile bestätigt. Die Zeile wurde möglicherweise gespeichert, auch wenn die Zähler für erstellt und aktualisiert null sind. Prüfen Sie einige betroffene Kontakte, bevor Sie es erneut versuchen. Lassen Sie den Import-Tab geöffnet, bis der Vorgang abgeschlossen ist; das Dashboard führt den Import über diesen Tab aus.

Um aus Ihrer eigenen Datenbank zu synchronisieren, skripten Sie CLI oder rufen Sie den Batch-Endpunkt auf. bird contacts create <email> fügt einen einzelnen hinzu. bird contacts batch führt ein Upsert von bis zu 1.000 in einem einzigen Aufruf durch. Verwenden Sie einen Batch pro Durchlauf statt einer Anfrage pro Person, um Ihre Kontaktliste mit Ihrem System synchron zu halten.

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

Jeder Batch-Eintrag wird automatisch anhand der mitgelieferten Identifikatoren abgeglichen (E-Mail-Adresse, Telefonnummer oder externe ID), und das optionale Feld match_on erzwingt den Abgleich auf einen einzigen davon. Ein Eintrag kann auch benutzerdefinierte Eigenschaftswerte setzen und jeden Kontakt in der Anfrage direkt über audience_ids in Audiences einordnen. Jeder Eintrag gelingt oder scheitert einzeln, und die Antwort liefert ein Ergebnis pro Eintrag in Einreichungsreihenfolge:

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

Wenn die Identifikatoren eines Eintrags auf verschiedene bestehende Kontakte verweisen, schlägt der Eintrag mit einem Konflikt zur Überprüfung fehl. Bereinigen Sie den Quelldatensatz, bevor Sie es erneut versuchen; der Batch führt diese Kontakte nicht zusammen.

Zwei Standardeinstellungen sind für eine Synchronisierung nützlich. Ein Batch führt data-Schlüssel mit vorhandenen Kontaktdaten zusammen, sodass ein Import, der ein Attribut ändert, nie die anderen löscht. Senden Sie einen null-Wert, um einen Schlüssel zu leeren, oder setzen Sie data_mode: "replace", um die gesamte Map zu überschreiben. Setzen Sie Ihre eigene external_id bei jedem Kontakt, damit eine spätere Synchronisierung dieselbe Person auch dann findet, wenn sich ihre E-Mail-Adresse ändert. Im Batch-Beispiel existiert user_2214 bereits, sodass der Eintrag zu diesem Kontakt aufgelöst wird und die neue E-Mail-Adresse direkt überschreibt.

Einen Kontakt löschen

Das Löschen eines Kontakts ist endgültig: Der Datensatz und seine Audience-Mitgliedschaften werden entfernt, und nichts stellt sie wieder her. Unterdrückungen und Präferenzen bleiben jedoch unberührt. Eine Adresse, die einen Hard Bounce verursacht hat, bleibt auf Ihrer Unterdrückungsliste, und eine abgemeldete Adresse behält ihre Opt-out-Präferenz, auch nachdem Sie den Kontakt gelöscht haben – so wird durch das Löschen niemand stillschweigend wieder zustellbar.

Nächste Schritte

• Audiences: Kontakte in wiederverwendbare Listen gruppieren
• Unterdrückungen: die Workspace-Liste der Adressen, an die nicht zugestellt wird, getrennt von Ihren Kontakten geführt
• Batch-Versand: viele Empfänger in einem Aufruf erreichen, bis zu 100 Nachrichten pro Anfrage
• CLI: Kontakte, Eigenschaften und Zielgruppen mit dem Befehl bird skripten
• API-Referenz: vollständige Request- und Response-Schemas