Kontakte
Kontaktprofile und eigene Felder verwalten, gesammelt oder einzeln.
Kontakt erstellen
Erstellt einen Kontakt und meldet ihn optional bei Kontaktlisten an.
/contactsErfordert einen API-Schlüssel mit dem Scope full. E-Mail-Adressen sind pro Workspace eindeutig und werden in Kleinbuchstaben gespeichert; das Erstellen eines bereits vorhandenen Kontakts gibt 409 mit dem vorhandenen Kontakt in existing zurück. Löst contact.created aus und für jede Kontaktliste subscriber.created. Siehe Kontakte.
Body-Parameter
emailstringerforderlichfirst_namestringlast_namestringcustom_fieldsobjectWerte nach Schlüssel des eigenen Felds, etwa {"company": "Analytical Engines"}. Werte für Datumsfelder müssen das Format YYYY-MM-DD haben. Schlüssel, die zu keinem eigenen Feld passen, werden unverändert gespeichert.
audiencesstring[]aud_…), bei denen der Kontakt angemeldet wird. IDs, die im Workspace nicht existieren, werden übersprungen.unsubscribedbooleanStandardwert: falsetrue erstellt den Kontakt als abgemeldet. Kampagnen überspringen abgemeldete Kontakte; ihre Mitgliedschaften in Kontaktlisten beginnen als abgemeldet.
Rückgabe
Gibt 201 mit dem Kontakt-Objekt zurück. Hier listet audiences jede Kontaktliste mit id, name und dem Status subscribed auf. Alle Felder finden Sie unter Kontakt abrufen.
Gibt 422 mit usage zurück, wenn eine Kontaktliste das Abonnentenlimit Ihres Tarifs erreicht hat. In diesem Fall wird kein Kontakt erstellt.
{
"object": "contact",
"id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
"email": "ada@example.com",
"first_name": "Ada",
"last_name": "Lovelace",
"custom_fields": {
"company": "Analytical Engines",
"plan": "pro"
},
"unsubscribed": false,
"audiences": [
{
"id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
"name": "Newsletter",
"subscribed": true
}
],
"created_at": "2026-10-01T10:20:31.704113Z",
"updated_at": "2026-10-01T10:20:31.704113Z"
}{
"error": "Custom field \"Birthday\" must be a date in YYYY-MM-DD format"
}{
"error": "Contact with this email already exists",
"existing": {
"object": "contact",
"id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
"email": "ada@example.com",
"first_name": "Ada",
"last_name": "Lovelace",
"custom_fields": {
"company": "Analytical Engines",
"plan": "pro"
},
"unsubscribed": false,
"audiences": [
{
"id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
"name": "Newsletter",
"subscribed": true
}
],
"created_at": "2026-10-01T10:20:31.704113Z",
"updated_at": "2026-10-01T10:20:31.704113Z"
}
}{
"error": "Pro includes 50,000 subscribers per audience.",
"usage": {
"used": 50000,
"limit": 50000,
"plan": "pro"
}
}Kontakt abrufen
Ruft einen Kontakt mit seinen eigenen Feldern und Mitgliedschaften in Kontaktlisten ab.
/contacts/{id}Erfordert einen API-Schlüssel mit dem Scope full.
Pfadparameter
idstringerforderlichcon_…) oder seine E-Mail-Adresse, URL-kodiert.Rückgabe
Gibt das Kontakt-Objekt zurück.
objectstringcontact.idstringemailstringfirst_namestring | nulllast_namestring | nullcustom_fieldsobject{}, wenn keine vorhanden sind.unsubscribedbooleantrue, wenn sich der Kontakt von allen Kampagnen abgemeldet hat.audiencesobject[]Die Kontaktlisten, zu denen der Kontakt gehört, jeweils mit id, name und einem Objekt subscriber: id (sub_…), subscribed, subscribed_at, unsubscribed_at, created_at und updated_at.
created_atstringupdated_atstring{
"object": "contact",
"id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
"email": "ada@example.com",
"first_name": "Ada",
"last_name": "Lovelace",
"custom_fields": {
"company": "Analytical Engines",
"plan": "pro"
},
"unsubscribed": false,
"audiences": [
{
"id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
"name": "Newsletter",
"subscriber": {
"id": "sub_4KECYl5AwXEy8ezswYRhuddttxo",
"subscribed": true,
"subscribed_at": "2026-10-01T10:20:31.000000Z",
"unsubscribed_at": null,
"created_at": "2026-10-01T10:20:31.000000Z",
"updated_at": "2026-10-01T10:20:31.000000Z"
}
}
],
"created_at": "2026-10-01T10:20:31.000000Z",
"updated_at": "2026-10-01T10:20:31.000000Z"
}{
"error": "Contact not found"
}Kontakt aktualisieren
Aktualisiert einen Kontakt. Nur die gesendeten Felder ändern sich.
/contacts/{id}Erfordert einen API-Schlüssel mit dem Scope full. Löst contact.updated aus, mit den vorherigen Werten geänderter Felder in previous. Eine Änderung von audiences löst zusätzlich subscriber.created und subscriber.deleted für die hinzugefügten und entfernten Mitgliedschaften aus.
Pfadparameter
idstringerforderlichcon_…) oder seine E-Mail-Adresse, URL-kodiert.Body-Parameter
emailstringfirst_namestringlast_namestringcustom_fieldsobjectunsubscribedbooleantrue meldet den Kontakt von allen Kampagnen ab, false meldet ihn erneut an. Bestehende Mitgliedschaften in Kontaktlisten behalten ihren eigenen Status.audiencesstring[]Die vollständige Liste der IDs der Kontaktlisten, zu denen der Kontakt gehören soll. Der Kontakt wird den Kontaktlisten hinzugefügt, in denen er noch nicht ist, und aus den Kontaktlisten entfernt, die nicht in Ihrer Liste stehen. Senden Sie [], um ihn aus allen Kontaktlisten zu entfernen. Um eine einzelne Kontaktliste hinzuzufügen oder zu entfernen, ohne alle aufzuzählen, nutzen Sie Abonnent hinzufügen oder Abonnent löschen.
Rückgabe
Gibt den aktualisierten Kontakt im selben Format wie Kontakt abrufen zurück. Eine Anfrage ohne eines dieser Felder gibt 400 zurück.
curl -X POST https://api.emailit.com/v2/contacts/ada%40example.com \
-H "Authorization: Bearer $EMAILIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"custom_fields": { "company": "Analytical Engines", "plan": "business" },
"audiences": ["aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "aud_4KOlh9t2uw5od4qypqCtyrZyDq2"]
}'{
"object": "contact",
"id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
"email": "ada@example.com",
"first_name": "Augusta",
"last_name": "Lovelace",
"custom_fields": {
"company": "Analytical Engines",
"plan": "pro"
},
"unsubscribed": false,
"audiences": [
{
"id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
"name": "Newsletter",
"subscriber": {
"id": "sub_4KECYl5AwXEy8ezswYRhuddttxo",
"subscribed": true,
"subscribed_at": "2026-10-01T10:20:31.000000Z",
"unsubscribed_at": null,
"created_at": "2026-10-01T10:20:31.000000Z",
"updated_at": "2026-10-01T10:20:31.000000Z"
}
}
],
"created_at": "2026-10-01T10:20:31.000000Z",
"updated_at": "2026-10-02T09:03:17.000000Z"
}{
"error": "No valid fields provided for update. Provide at least one of: email, first_name, last_name, custom_fields, unsubscribed, audiences"
}{
"error": "Contact not found"
}{
"error": "Another contact with this email already exists"
}Kontakte auflisten
Gibt eine Seite mit Kontakten zurück, die neuesten zuerst.
/contactsErfordert einen API-Schlüssel mit dem Scope full. Mit denselben Parametern laden Sie über Kontakte exportieren alle Treffer als Datei herunter.
Query-Parameter
pageintegerStandardwert: 1limitintegerStandardwert: 10searchstringq funktioniert ebenfalls.audience_idstringaud_…).unsubscribedbooleantrue oder false. Nur Kontakte mit diesem Abmeldestatus.sortstringStandardwert: created_atemail, first_name, last_name, name, audiences, created_at oder updated_at.orderstringStandardwert: descasc oder desc. Bei diesem Endpunkt ist order die Sortierrichtung, nicht der Sortierschlüssel.matchstringStandardwert: allall oder or. Wie die Filter unten kombiniert werden.Filter
Fügen Sie Filter als key.condition=value hinzu, zum Beispiel email.ends_with=@acme.com oder custom_fields.plan.exact=pro. Siehe Filtern und Sortieren.
| Schlüssel | Typ | Hinweise |
|---|---|---|
email |
string | |
first_name |
string | |
last_name |
string | |
name |
string | Vor- und Nachname, durch ein Leerzeichen verbunden. |
audiences |
string | Der alphabetisch erste Name einer Kontaktliste des Kontakts. |
unsubscribed |
boolean | |
created_at |
date | |
updated_at |
date | |
audience_id |
string | Nur exact und not_exact. Der Wert ist die ID einer Kontaktliste. |
custom_fields.<key> |
string | Ersetzen Sie <key> durch den Schlüssel eines eigenen Felds. Werte werden als Text verglichen. |
Die älteren Parameter filter[audience_id], filter[unsubscribed] und filter[custom_fields][<key>] funktionieren weiterhin.
Rückgabe
dataobject[]audiences als id, name und subscribed. Siehe Kontakt abrufen.total_recordsintegernext_page_urlstring | nullnull. Siehe Paginierung.previous_page_urlstring | nullnull.curl -G https://api.emailit.com/v2/contacts \
-H "Authorization: Bearer $EMAILIT_API_KEY" \
--data-urlencode "audience_id=aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2" \
--data-urlencode "custom_fields.plan.exact=pro" \
--data-urlencode "sort=email" \
--data-urlencode "order=asc" \
--data-urlencode "limit=100"{
"data": [
{
"object": "contact",
"id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
"email": "ada@example.com",
"first_name": "Ada",
"last_name": "Lovelace",
"custom_fields": {
"company": "Analytical Engines",
"plan": "pro"
},
"unsubscribed": false,
"audiences": [
{
"id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
"name": "Newsletter",
"subscribed": true
}
],
"created_at": "2026-10-01T10:20:31.704113Z",
"updated_at": "2026-10-01T10:20:31.704113Z"
},
{
"object": "contact",
"id": "con_4KiXIs4xLTcJIAHnKJaLcnMZYh7",
"email": "grace@example.com",
"first_name": "Grace",
"last_name": "Hopper",
"custom_fields": {},
"unsubscribed": true,
"audiences": [],
"created_at": "2026-09-28T07:55:02.118342Z",
"updated_at": "2026-09-30T18:11:40.902215Z"
}
],
"total_records": 2,
"next_page_url": null,
"previous_page_url": null
}Kontakte gesammelt aktualisieren
Führt eine Aktion für bis zu 100 Kontakte in einer einzigen Anfrage aus.
/contacts/bulkErfordert einen API-Schlüssel mit dem Scope full. Jede ID muss zu einem Kontakt im Workspace gehören, sonst wird nichts geändert und die Antwort listet die fehlenden IDs in missing auf. Jeder Kontakt löst dieselben Events aus wie bei den Endpunkten für einzelne Kontakte. Erreicht die Kontaktliste während add_to_audience das Abonnentenlimit Ihres Tarifs, bricht die Anfrage mit 422 ab; die bis dahin verarbeiteten Kontakte bleiben hinzugefügt.
| Aktion | Was passiert |
|---|---|
delete |
Löscht die Kontakte und ihre Mitgliedschaften in Kontaktlisten, wie Kontakt löschen. |
add_to_audience |
Fügt die Kontakte der Kontaktliste audience_id hinzu. Kontakte, die bereits darin sind, bleiben unverändert. |
remove_from_audience |
Entfernt die Kontakte aus der Kontaktliste audience_id. |
unsubscribe |
Setzt unsubscribed auf true, sodass Kampagnen die Kontakte überspringen. |
resubscribe |
Setzt unsubscribed auf false. |
Body-Parameter
actionstringerforderlichdelete, add_to_audience, remove_from_audience, unsubscribe oder resubscribe.idsstring[]erforderlichcon_…), von 1 bis 100. E-Mail-Adressen werden hier nicht akzeptiert. Duplikate werden ignoriert.audience_idstringadd_to_audience und remove_from_audience.Rückgabe
objectstringcontact_bulk.actionstringprocessedintegeridsstring[]{
"object": "contact_bulk",
"action": "add_to_audience",
"processed": 2,
"ids": ["con_4K9kQdrXth7am0TPKvPrR5yd2oo", "con_4KiXIs4xLTcJIAHnKJaLcnMZYh7"]
}{
"error": "A maximum of 100 contacts can be updated per request"
}{
"error": "One or more contacts were not found",
"missing": ["con_4K3pZc1Q9nWm2LrT8vYb5Hd0XaE"]
}{
"error": "Pro includes 50,000 subscribers per audience.",
"usage": {
"used": 50000,
"limit": 50000,
"plan": "pro"
}
}Kontakte exportieren
Lädt passende Kontakte als CSV- oder XLSX-Datei herunter.
/contacts/exportErfordert einen API-Schlüssel mit dem Scope full. Akzeptiert dieselben Such-, Filter- und Sortierparameter wie Kontakte auflisten, übergeben im Query-String, ohne Paginierung. POST /contacts/export funktioniert genauso. Ein Export kann bis zu 10.000 Kontakte enthalten; passen mehr, gibt die Anfrage 422 zurück. Grenzen Sie dann die Filter weiter ein.
Query-Parameter
formatstringStandardwert: csvcsv oder xlsx.search, audience_id, unsubscribed, sort, order, match, key.conditionstringRückgabe
Gibt die Datei als Anhang zurück: contacts.csv (text/csv; charset=utf-8) oder contacts.xlsx. Jede Zeile ist ein Kontakt mit diesen Spalten:
| Spalte | Inhalt |
|---|---|
email |
Die E-Mail-Adresse. |
first_name, last_name |
Vor- und Nachname. |
unsubscribed |
true oder false. |
audiences |
Die Namen der Kontaktlisten des Kontakts, getrennt durch ; . |
| Eine Spalte pro eigenem Feld | Der Wert jedes im Workspace definierten eigenen Felds, benannt nach seinem Schlüssel. Listen werden mit ; verbunden. |
created_at, updated_at |
Zeitstempel im Format ISO 8601. |
email,first_name,last_name,unsubscribed,audiences,company,plan,created_at,updated_at
ada@example.com,Ada,Lovelace,false,Newsletter,Analytical Engines,pro,2026-10-01T10:20:31.000000Z,2026-10-01T10:20:31.000000Z{
"error": "format must be csv or xlsx"
}{
"error": "Export is limited to 10000 contacts. Narrow your filters and try again."
}Kontakt löschen
Löscht einen Kontakt mit all seinen Mitgliedschaften in Kontaktlisten endgültig.
/contacts/{id}Erfordert einen API-Schlüssel mit dem Scope full. Das Löschen lässt sich nicht rückgängig machen. Wenn Sie jemandem keine E-Mails mehr senden, den Datensatz aber behalten möchten, aktualisieren Sie den Kontakt mit unsubscribed: true oder setzen Sie die Adresse auf Ihre Sperrliste. Löst für jede Mitgliedschaft subscriber.deleted aus, danach contact.deleted.
Pfadparameter
idstringerforderlichcon_…) oder seine E-Mail-Adresse, URL-kodiert.Rückgabe
objectstringcontact.idstringemailstringdeletedbooleantrue.{
"object": "contact",
"id": "con_4Kt4ZXloQR8WGcMsYx8PFCUjokM",
"email": "alan@example.com",
"deleted": true
}{
"error": "Contact not found"
}