Kontakte
Die Personen, denen Sie Marketing-E-Mails senden, mit ihrem Abo-Status und eigenen Eigenschaften.
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 und Themen 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 liefert409. Eine Adresse, die nie E-Mails empfangen kann (zum Beispielexample.com, ein.test-Name oder eine Domain ohne Mailserver), liefert422.first_name,last_name.unsubscribed: Ihre teamweite Abmeldung. Solange sietrueist, 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 mitdomain_id,nameundunsubscribed_at. E-Mails dieser Domains überspringen den Kontakt, Ihre anderen Domains erreichen ihn weiterhin. Siehe Abmeldungen.verification_statusundverified_at: nur lesbar. Das Ergebnis der letzten Tiefenprüfung des Kontakts,null, bis er geprüft wurde. Siehe Verifizierung.properties: eigene Werte wieplan: "pro"odercity: "Berlin". Werte sind Strings oder Zahlen (verschachtelte Objekte oder Arrays liefern422), mit höchstens 100 Schlüsseln pro Kontakt. Eigenschaften füllen die Platzhalter in Vorlagen und die Filter von Segmenten.PATCHführt sie Schlüssel für Schlüssel zusammen, und ein Wertnullentfernt 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.
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 mit409(existiert bereits) oder422(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).
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" }]'
{
"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.
Ereignisse
Jede Änderung veröffentlicht ein Webhook-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.