---
title: Kontakte
description: Die Personen, denen Sie Marketing-E-Mails senden, mit ihrem Abo-Status und eigenen Eigenschaften.
ai:
  exclude: true
---

Ein Kontakt ist eine E-Mail-Adresse in der Liste Ihres Teams. Jede Adresse kommt nur einmal vor (Groß- und Kleinschreibung spielt keine Rolle), und mit [Segmenten](/docs/de/concepts/segments) und [Themen](/docs/de/concepts/topics) legen Sie fest, wer einen Newsletter-Versand erhält. Verwalten Sie Kontakte im Dashboard unter **Zielgruppe** oder über die API.

## Was ein Kontakt enthält

- `email`: die Adresse. Ein zweiter Kontakt mit derselben Adresse liefert `409`. Eine Adresse, die nie E-Mails empfangen kann (zum Beispiel `example.com`, ein `.test`-Name oder eine Domain ohne Mailserver), liefert `422`.
- `first_name`, `last_name`.
- `unsubscribed`: Ihre teamweite Abmeldung. Solange sie `true` ist, erhält der Kontakt von keiner Ihrer Domains Marketing-E-Mails. Nur Sie setzen sie; die Abmeldung eines Empfängers ändert sie nie.
- `unsubscribed_domains`: nur lesbar. Die Domains, von denen sich der Kontakt über einen Abmeldelink abgemeldet hat, jeweils mit `domain_id`, `name` und `unsubscribed_at`. E-Mails dieser Domains überspringen den Kontakt, Ihre anderen Domains erreichen ihn weiterhin. Siehe [Abmeldungen](/docs/de/concepts/unsubscribes).
- `verification_status` und `verified_at`: nur lesbar. Das Ergebnis der letzten Tiefenprüfung des Kontakts, `null`, bis er geprüft wurde. Siehe [Verifizierung](/docs/de/concepts/verification).
- `properties`: eigene Werte wie `plan: "pro"` oder `city: "Berlin"`. Werte sind Strings oder Zahlen (verschachtelte Objekte oder Arrays liefern `422`), mit höchstens 100 Schlüsseln pro Kontakt. Eigenschaften füllen die Platzhalter in Vorlagen und die Filter von Segmenten. `PATCH` führt sie Schlüssel für Schlüssel zusammen, und ein Wert `null` entfernt den Schlüssel.

## Anlegen und lesen

`POST /contacts`, `GET /contacts`, `GET /contacts/{id}`, `PATCH /contacts/{id}` und `DELETE /contacts/{id}`. In `{id}` können Sie die ID des Kontakts oder seine E-Mail-Adresse verwenden.

```sh
curl -X POST "https://api.billionsend.com/contacts" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ana@acme.com",
    "first_name": "Ana",
    "properties": { "plan": "pro" }
  }'
```

Fügen Sie `include=properties,topics` zu `GET /contacts` oder `GET /segments/{id}/contacts` hinzu, um die Eigenschaften und Themenauswahl jedes Kontakts in derselben Antwort zu erhalten. `POST /contacts/batch/get` liest bis zu 1.000 Kontakte per ID oder E-Mail-Adresse in einem Aufruf, in der Reihenfolge der Anfrage; Adressen ohne Treffer stehen unter `missing`.

`PATCH /contacts/{id}/topics` setzt die Themenauswahl eines Kontakts, und `GET /contacts/{id}/topics` liest sie samt den angewendeten Standardwerten der Themen wieder aus.

`POST /contacts/{id}/preferences-link` liefert einen Link zur Einstellungsseite des Kontakts, den Sie etwa aus einem Einstellungsbildschirm in Ihrem Produkt öffnen können. Der Link läuft nicht ab und erlaubt seinem Inhaber, die Auswahl dieses Kontakts zu ändern. Geben Sie ihn deshalb nur an den Kontakt selbst weiter. Er öffnet die Standardseite des Teams und meldet den Kontakt von jeder Domain ab.

## Massenanlage

`POST /contacts/batch` nimmt 1 bis 1.000 Kontakte in einer Anfrage entgegen und schreibt sie gemeinsam.

`on_conflict` legt fest, was passiert, wenn eine Adresse bereits existiert oder sich im Batch wiederholt:

- `error` (Standard): Dieser Eintrag schlägt mit `409` (existiert bereits) oder `422` (Wiederholung) fehl.
- `skip`: Der bestehende Kontakt bleibt unverändert.
- `upsert`: Der Eintrag wird in den bestehenden Kontakt eingemischt. Namen nur, wenn Sie sie senden, Eigenschaften Schlüssel für Schlüssel, Segmente werden hinzugefügt, Themen aktualisiert.

Ein Batch meldet niemanden wieder an: `unsubscribed: false` bei einem Kontakt, der bereits abgemeldet ist, wird ignoriert. Verwenden Sie dafür `PATCH /contacts/{id}`.

Der Header `x-batch-validation` wählt `strict` (Standard: ein fehlerhafter Eintrag lehnt den gesamten Batch ab) oder `permissive` (gültige Einträge werden geschrieben, Fehler stehen in `errors`).

```sh
curl -X POST "https://api.billionsend.com/contacts/batch?on_conflict=upsert" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -H "x-batch-validation: permissive" \
  -d '[{ "email": "ana@acme.com", "properties": { "plan": "pro" } }, { "email": "not-an-address" }]'
```

```json
{
  "data": [{ "object": "contact", "index": 0, "id": "9b2f…", "status": "updated" }],
  "counts": { "created": 0, "updated": 1, "skipped": 0, "failed": 1 },
  "errors": [{ "index": 1, "statusCode": 422, "name": "validation_error", "message": "email: Invalid email address" }]
}
```

## Massenlöschung

`POST /contacts/batch/remove` löscht bis zu 1.000 Kontakte per `ids` oder `emails` (eines von beiden) und gibt die gelöschten zurück. Mit `erase: true` entfernen Sie jede Adresse zusätzlich aus dem E-Mail-Verlauf, den Ereignis-Payloads und den API-Logs. `DELETE /contacts/{id}?erase=true` tut dasselbe für einen einzelnen Kontakt.

## CSV-Import und -Export

Im Dashboard importiert **Kontakte** eine CSV-Datei und exportiert die aktuelle Ansicht (einschließlich eines Filters nach Segment, Thema oder Domain) zurück in eine CSV-Datei. Der Export hat eine Spalte `unsubscribed` und eine Spalte `unsubscribed_domains` (`*` steht für das gesamte Team). Zeilen mit einer Adresse, die nie E-Mails empfangen kann, werden übersprungen. In einem kostenpflichtigen Tarif kann der Import-Dialog die neuen Adressen auch verifizieren, siehe [Verifizierung](/docs/de/concepts/verification).

## Ereignisse

Jede Änderung veröffentlicht ein [Webhook](/docs/de/concepts/webhooks)-Ereignis: `contact.created`, `contact.updated`, `contact.deleted`, `contact.unsubscribed`, `contact.resubscribed`, `contact.topic_opt_in` und `contact.topic_opt_out`.

## Limits

| | Free | Starter, Pro, Scale |
| --- | --- | --- |
| Kontakte pro Team | 1.000 | Kein Limit |

Über dem Limit liefert das Anlegen eines Kontakts `403 plan_limit_reached`. Bestehende Kontakte lassen sich weiterhin aktualisieren.
