Zum Inhalt springen
Doku

Kontaktprofile und eigene Felder verwalten, gesammelt oder einzeln.

Basis-URLhttps://api.emailit.com/v2AuthentifizierungFehlerRate Limits

Kontakt erstellen

Erstellt einen Kontakt und meldet ihn optional bei Kontaktlisten an.

POST/contacts

Erfordert 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

emailstringerforderlich
Die E-Mail-Adresse des Kontakts.
first_namestring
Der Vorname.
last_namestring
Der Nachname.
custom_fieldsobject

Werte 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[]
IDs der Kontaktlisten (aud_…), bei denen der Kontakt angemeldet wird. IDs, die im Workspace nicht existieren, werden übersprungen.
unsubscribedbooleanStandardwert: false

true 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.

POST/contacts
Terminal
curl -X POST https://api.emailit.com/v2/contacts \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada@example.com",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "custom_fields": { "company": "Analytical Engines", "plan": "pro" },
    "audiences": ["aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2"]
  }'
JSON
{
  "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"
}

Kontakt abrufen

Ruft einen Kontakt mit seinen eigenen Feldern und Mitgliedschaften in Kontaktlisten ab.

GET/contacts/{id}

Erfordert einen API-Schlüssel mit dem Scope full.

Pfadparameter

idstringerforderlich
Die ID des Kontakts (con_…) oder seine E-Mail-Adresse, URL-kodiert.

Rückgabe

Gibt das Kontakt-Objekt zurück.

objectstring
Immer contact.
idstring
Die ID des Kontakts.
emailstring
Die E-Mail-Adresse in Kleinbuchstaben.
first_namestring | null
Der Vorname.
last_namestring | null
Der Nachname.
custom_fieldsobject
Werte eigener Felder nach Schlüssel. {}, wenn keine vorhanden sind.
unsubscribedboolean
true, 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_atstring
Zeitpunkt der Erstellung des Kontakts.
updated_atstring
Zeitpunkt der letzten Änderung des Kontakts.
GET/contacts/{id}
Terminal
curl https://api.emailit.com/v2/contacts/con_4K9kQdrXth7am0TPKvPrR5yd2oo \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
JSON
{
  "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"
}

Kontakt aktualisieren

Aktualisiert einen Kontakt. Nur die gesendeten Felder ändern sich.

POST/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

idstringerforderlich
Die ID des Kontakts (con_…) oder seine E-Mail-Adresse, URL-kodiert.

Body-Parameter

emailstring
Eine neue E-Mail-Adresse. Darf keinem anderen Kontakt gehören.
first_namestring
Der Vorname.
last_namestring
Der Nachname.
custom_fieldsobject
Werte eigener Felder nach Schlüssel. Ersetzt alle eigenen Felder des Kontakts; geben Sie also auch die an, die Sie behalten möchten.
unsubscribedboolean
true 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.

POST/contacts/{id}
Terminal
curl -X POST https://api.emailit.com/v2/contacts/con_4K9kQdrXth7am0TPKvPrR5yd2oo \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"first_name": "Augusta"}'
Terminal
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"]
  }'
JSON
{
  "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"
}

Kontakte auflisten

Gibt eine Seite mit Kontakten zurück, die neuesten zuerst.

GET/contacts

Erfordert einen API-Schlüssel mit dem Scope full. Mit denselben Parametern laden Sie über Kontakte exportieren alle Treffer als Datei herunter.

Query-Parameter

pageintegerStandardwert: 1
Die abzurufende Seite.
limitintegerStandardwert: 10
Kontakte pro Seite, von 1 bis 100.
audience_idstring
Nur Kontakte in dieser Kontaktliste (aud_…).
unsubscribedboolean
true oder false. Nur Kontakte mit diesem Abmeldestatus.
sortstringStandardwert: created_at
email, first_name, last_name, name, audiences, created_at oder updated_at.
orderstringStandardwert: desc
asc oder desc. Bei diesem Endpunkt ist order die Sortierrichtung, nicht der Sortierschlüssel.
matchstringStandardwert: all
all 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[]
Die Kontakte auf dieser Seite, jeweils mit audiences als id, name und subscribed. Siehe Kontakt abrufen.
total_recordsinteger
Die Anzahl der passenden Kontakte über alle Seiten hinweg.
next_page_urlstring | null
Pfad der nächsten Seite mit Ihren Filtern oder null. Siehe Paginierung.
previous_page_urlstring | null
Pfad der vorherigen Seite oder null.
GET/contacts
Terminal
curl https://api.emailit.com/v2/contacts \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
Terminal
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"
JSON
{
  "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.

POST/contacts/bulk

Erfordert 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

actionstringerforderlich
delete, add_to_audience, remove_from_audience, unsubscribe oder resubscribe.
idsstring[]erforderlich
Kontakt-IDs (con_…), von 1 bis 100. E-Mail-Adressen werden hier nicht akzeptiert. Duplikate werden ignoriert.
audience_idstring
Die ID der Kontaktliste. Erforderlich für add_to_audience und remove_from_audience.

Rückgabe

objectstring
Immer contact_bulk.
actionstring
Die ausgeführte Aktion.
processedinteger
Wie viele Kontakte verarbeitet wurden.
idsstring[]
Die IDs der verarbeiteten Kontakte.
POST/contacts/bulk
Terminal
curl -X POST https://api.emailit.com/v2/contacts/bulk \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "add_to_audience", "ids": ["con_4K9kQdrXth7am0TPKvPrR5yd2oo", "con_4KiXIs4xLTcJIAHnKJaLcnMZYh7"], "audience_id": "aud_4KOlh9t2uw5od4qypqCtyrZyDq2"}'
JSON
{
  "object": "contact_bulk",
  "action": "add_to_audience",
  "processed": 2,
  "ids": ["con_4K9kQdrXth7am0TPKvPrR5yd2oo", "con_4KiXIs4xLTcJIAHnKJaLcnMZYh7"]
}

Kontakte exportieren

Lädt passende Kontakte als CSV- oder XLSX-Datei herunter.

GET/contacts/export

Erfordert 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: csv
csv oder xlsx.
search, audience_id, unsubscribed, sort, order, match, key.conditionstring
Dieselben Parameter wie bei Kontakte auflisten.

Rü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.
GET/contacts/export
Terminal
curl "https://api.emailit.com/v2/contacts/export?format=csv&audience_id=aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2" \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -o contacts.csv
Text
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

Kontakt löschen

Löscht einen Kontakt mit all seinen Mitgliedschaften in Kontaktlisten endgültig.

DELETE/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

idstringerforderlich
Die ID des Kontakts (con_…) oder seine E-Mail-Adresse, URL-kodiert.

Rückgabe

objectstring
Immer contact.
idstring
Die ID des gelöschten Kontakts.
emailstring
Die E-Mail-Adresse des Kontakts.
deletedboolean
Immer true.
DELETE/contacts/{id}
Terminal
curl -X DELETE https://api.emailit.com/v2/contacts/con_4Kt4ZXloQR8WGcMsYx8PFCUjokM \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
JSON
{
  "object": "contact",
  "id": "con_4Kt4ZXloQR8WGcMsYx8PFCUjokM",
  "email": "alan@example.com",
  "deleted": true
}

War diese Seite hilfreich?

Danke für Ihr Feedback.

Danke, wir lesen jede Nachricht.