# Kontakte API

> Kontaktprofile und eigene Felder verwalten, gesammelt oder einzeln.

Basis-URL: `https://api.emailit.com/v2`. Authentifizieren Sie sich mit `Authorization: Bearer <API key>`.

## Kontakt erstellen — POST /contacts

> Erstellen Sie einen Kontakt mit E-Mail-Adresse, Namen und eigenen Feldern und melden Sie ihn optional direkt bei einer oder mehreren Kontaktlisten an.

# 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](/de/docs/contacts/).

## Body-Parameter

- `email` (string, erforderlich): Die E-Mail-Adresse des Kontakts.

- `first_name` (string): Der Vorname.

- `last_name` (string): Der Nachname.

- `custom_fields` (object): Werte nach Schlüssel des [eigenen Felds](/de/docs/contacts/custom-fields/), 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.

- `audiences` (string[]): IDs der Kontaktlisten (`aud_…`), bei denen der Kontakt angemeldet wird. IDs, die im Workspace nicht existieren, werden übersprungen.

- `unsubscribed` (boolean): `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](/de/docs/api-reference/contacts/get/).

Gibt `422` mit `usage` zurück, wenn eine Kontaktliste das Abonnentenlimit Ihres Tarifs erreicht hat. In diesem Fall wird kein Kontakt erstellt.

**Anfrage** `POST /contacts`

**Node.js**

```javascript
import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const contact = await emailit.contacts.create({
  email: 'ada@example.com',
  first_name: 'Ada',
  last_name: 'Lovelace',
});
```

**Python**

```python
from emailit import EmailitClient
client = EmailitClient("your_api_key")

contact = client.contacts.create({
  "email": "ada@example.com",
  "first_name": "Ada",
  "last_name": "Lovelace",
})
```

**PHP**

```php
$emailit = Emailit::client('your_api_key');

$contact = $emailit->contacts()->create([
  'email' => 'ada@example.com',
  'first_name' => 'Ada',
  'last_name' => 'Lovelace',
]);
```

**Ruby**

```ruby
require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

contact = client.contacts.create(
  email: "ada@example.com",
  first_name: "Ada",
  last_name: "Lovelace"
)
```

**Go**

```go
import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

contact, err := client.Contacts.Create(&emailit.CreateContactRequest{
  Email:     "ada@example.com",
  FirstName: "Ada",
  LastName:  "Lovelace",
})
```

**Rust**

```rust
use emailit::Emailit;

let emailit = Emailit::new("your_api_key");

let contact = emailit.contacts.create(
  emailit::types::CreateContactParams::new("ada@example.com")
    .with_first_name("Ada")
    .with_last_name("Lovelace")
).await?;
```

**Java**

```java
import com.emailit.*;
import com.emailit.params.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject contact = emailit.contacts().create(
  ContactCreateParams.builder()
    .setEmail("ada@example.com")
    .setFirstName("Ada")
    .setLastName("Lovelace")
    .build()
);
```

**.NET**

```csharp
using Emailit;

var emailit = new EmailitClient("your_api_key");

var contact = emailit.Contacts.Create(new ContactCreateOptions {
  Email = "ada@example.com",
  FirstName = "Ada",
  LastName = "Lovelace",
});
```

**Laravel**

```php
use Emailit\Laravel\Facades\Emailit;

$contact = Emailit::contacts()->create([
  'email' => 'ada@example.com',
  'first_name' => 'Ada',
  'last_name' => 'Lovelace',
]);
```

**cURL**

```bash
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"]
  }'
```

**201**

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

**400**

```json
{
  "error": "Custom field \"Birthday\" must be a date in YYYY-MM-DD format"
}
```

**409**

```json
{
  "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"
  }
}
```

**422**

```json
{
  "error": "Pro includes 50,000 subscribers per audience.",
  "usage": {
    "used": 50000,
    "limit": 50000,
    "plan": "pro"
  }
}
```

---
Quelle: https://emailit.com/de/docs/api-reference/contacts/create/

## Kontakt abrufen — GET /contacts/{id}

> Rufen Sie einen Kontakt per ID oder E-Mail-Adresse ab, mit seinen eigenen Feldern und allen Mitgliedschaften in Kontaktlisten samt An- und Abmeldezeitpunkten.

# 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

- `id` (string, erforderlich): Die ID des Kontakts (`con_…`) oder seine E-Mail-Adresse, URL-kodiert.

## Rückgabe

Gibt das Kontakt-Objekt zurück.

- `object` (string): Immer `contact`.

- `id` (string): Die ID des Kontakts.

- `email` (string): Die E-Mail-Adresse in Kleinbuchstaben.

- `first_name` (string | null): Der Vorname.

- `last_name` (string | null): Der Nachname.

- `custom_fields` (object): Werte eigener Felder nach Schlüssel. `{}`, wenn keine vorhanden sind.

- `unsubscribed` (boolean): `true`, wenn sich der Kontakt von allen Kampagnen abgemeldet hat.

- `audiences` (object[]): 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_at` (string): Zeitpunkt der Erstellung des Kontakts.

- `updated_at` (string): Zeitpunkt der letzten Änderung des Kontakts.

**Anfrage** `GET /contacts/{id}`

**Node.js**

```javascript
import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const contact = await emailit.contacts.get('con_4K9kQdrXth7am0TPKvPrR5yd2oo');
```

**Python**

```python
from emailit import EmailitClient
client = EmailitClient("your_api_key")

contact = client.contacts.get("con_4K9kQdrXth7am0TPKvPrR5yd2oo")
```

**PHP**

```php
$emailit = Emailit::client('your_api_key');

$contact = $emailit->contacts()->get('con_4K9kQdrXth7am0TPKvPrR5yd2oo');
```

**Ruby**

```ruby
require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

contact = client.contacts.get("con_4K9kQdrXth7am0TPKvPrR5yd2oo")
```

**Go**

```go
import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

contact, err := client.Contacts.Get("con_4K9kQdrXth7am0TPKvPrR5yd2oo")
```

**Rust**

```rust
use emailit::Emailit;

let emailit = Emailit::new("your_api_key");

let contact = emailit.contacts.get("con_4K9kQdrXth7am0TPKvPrR5yd2oo").await?;
```

**Java**

```java
import com.emailit.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject contact = emailit.contacts().get("con_4K9kQdrXth7am0TPKvPrR5yd2oo");
```

**.NET**

```csharp
using Emailit;

var emailit = new EmailitClient("your_api_key");

var contact = emailit.Contacts.Get("con_4K9kQdrXth7am0TPKvPrR5yd2oo");
```

**Laravel**

```php
use Emailit\Laravel\Facades\Emailit;

$contact = Emailit::contacts()->get('con_4K9kQdrXth7am0TPKvPrR5yd2oo');
```

**cURL**

```bash
curl https://api.emailit.com/v2/contacts/con_4K9kQdrXth7am0TPKvPrR5yd2oo \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
```

**200**

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

**404**

```json
{
  "error": "Contact not found"
}
```

---
Quelle: https://emailit.com/de/docs/api-reference/contacts/get/

## Kontakt aktualisieren — POST /contacts/{id}

> Ändern Sie E-Mail-Adresse, Namen, eigene Felder oder Abmeldestatus eines Kontakts oder ersetzen Sie die Kontaktlisten, zu denen er gehört.

# 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

- `id` (string, erforderlich): Die ID des Kontakts (`con_…`) oder seine E-Mail-Adresse, URL-kodiert.

## Body-Parameter

- `email` (string): Eine neue E-Mail-Adresse. Darf keinem anderen Kontakt gehören.

- `first_name` (string): Der Vorname.

- `last_name` (string): Der Nachname.

- `custom_fields` (object): Werte eigener Felder nach Schlüssel. Ersetzt alle eigenen Felder des Kontakts; geben Sie also auch die an, die Sie behalten möchten.

- `unsubscribed` (boolean): `true` meldet den Kontakt von allen Kampagnen ab, `false` meldet ihn erneut an. Bestehende Mitgliedschaften in Kontaktlisten behalten ihren eigenen Status.

- `audiences` (string[]): 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](/de/docs/api-reference/audiences/subscribers/add/) oder [Abonnent löschen](/de/docs/api-reference/audiences/subscribers/delete/).

## Rückgabe

Gibt den aktualisierten Kontakt im selben Format wie [Kontakt abrufen](/de/docs/api-reference/contacts/get/) zurück. Eine Anfrage ohne eines dieser Felder gibt `400` zurück.

**Anfrage** `POST /contacts/{id}`

**Node.js**

```javascript
import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const contact = await emailit.contacts.update('con_4K9kQdrXth7am0TPKvPrR5yd2oo', {
  first_name: 'Augusta',
});
```

**Python**

```python
from emailit import EmailitClient
client = EmailitClient("your_api_key")

contact = client.contacts.update("con_4K9kQdrXth7am0TPKvPrR5yd2oo", {
  "first_name": "Augusta",
})
```

**PHP**

```php
$emailit = Emailit::client('your_api_key');

$contact = $emailit->contacts()->update('con_4K9kQdrXth7am0TPKvPrR5yd2oo', [
  'first_name' => 'Augusta',
]);
```

**Ruby**

```ruby
require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

contact = client.contacts.update("con_4K9kQdrXth7am0TPKvPrR5yd2oo",
  first_name: "Augusta"
)
```

**Go**

```go
import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

contact, err := client.Contacts.Update("con_4K9kQdrXth7am0TPKvPrR5yd2oo", &emailit.UpdateContactRequest{
  FirstName: "Augusta",
})
```

**Rust**

```rust
use emailit::Emailit;

let emailit = Emailit::new("your_api_key");

let contact = emailit.contacts.update("con_4K9kQdrXth7am0TPKvPrR5yd2oo",
  emailit::types::UpdateContactParams {
    first_name: Some("Augusta".into()),
    ..Default::default()
  }
).await?;
```

**Java**

```java
import com.emailit.*;
import com.emailit.params.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject contact = emailit.contacts().update("con_4K9kQdrXth7am0TPKvPrR5yd2oo", 
  ContactUpdateParams.builder()
    .setFirstName("Augusta")
    .build()
);
```

**.NET**

```csharp
using Emailit;

var emailit = new EmailitClient("your_api_key");

var contact = emailit.Contacts.Update("con_4K9kQdrXth7am0TPKvPrR5yd2oo", new ContactUpdateOptions {
  FirstName = "Augusta",
});
```

**Laravel**

```php
use Emailit\Laravel\Facades\Emailit;

$contact = Emailit::contacts()->update('con_4K9kQdrXth7am0TPKvPrR5yd2oo', [
  'first_name' => 'Augusta',
]);
```

**cURL**

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

**cURL**

```bash
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"]
  }'
```

**200**

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

**400**

```json
{
  "error": "No valid fields provided for update. Provide at least one of: email, first_name, last_name, custom_fields, unsubscribed, audiences"
}
```

**404**

```json
{
  "error": "Contact not found"
}
```

**409**

```json
{
  "error": "Another contact with this email already exists"
}
```

---
Quelle: https://emailit.com/de/docs/api-reference/contacts/update/

## Kontakte auflisten — GET /contacts

> Listen Sie die Kontakte eines Workspace auf, die neuesten zuerst, gefiltert nach Kontaktliste, Anmeldestatus, eigenen Feldern oder einem beliebigen Kontaktfeld.

# 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](/de/docs/api-reference/contacts/export/) alle Treffer als Datei herunter.

## Query-Parameter

- `page` (integer): Die abzurufende Seite.

- `limit` (integer): Kontakte pro Seite, von 1 bis 100.

- `search` (string): Abgleich mit E-Mail-Adresse, Vor- oder Nachname, ohne Beachtung der Groß-/Kleinschreibung. `q` funktioniert ebenfalls.

- `audience_id` (string): Nur Kontakte in dieser Kontaktliste (`aud_…`).

- `unsubscribed` (boolean): `true` oder `false`. Nur Kontakte mit diesem Abmeldestatus.

- `sort` (string): `email`, `first_name`, `last_name`, `name`, `audiences`, `created_at` oder `updated_at`.

- `order` (string): `asc` oder `desc`. Bei diesem Endpunkt ist `order` die Sortierrichtung, nicht der Sortierschlüssel.

- `match` (string): `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](/de/docs/api-reference/filtering/).

| 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

- `data` (object[]): Die Kontakte auf dieser Seite, jeweils mit `audiences` als `id`, `name` und `subscribed`. Siehe [Kontakt abrufen](/de/docs/api-reference/contacts/get/).

- `total_records` (integer): Die Anzahl der passenden Kontakte über alle Seiten hinweg.

- `next_page_url` (string | null): Pfad der nächsten Seite mit Ihren Filtern oder `null`. Siehe [Paginierung](/de/docs/api-reference/pagination/).

- `previous_page_url` (string | null): Pfad der vorherigen Seite oder `null`.

**Anfrage** `GET /contacts`

**Node.js**

```javascript
import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const contacts = await emailit.contacts.list();
```

**Python**

```python
from emailit import EmailitClient
client = EmailitClient("your_api_key")

contacts = client.contacts.list()
```

**PHP**

```php
$emailit = Emailit::client('your_api_key');

$contacts = $emailit->contacts()->list();
```

**Ruby**

```ruby
require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

contacts = client.contacts.list
```

**Go**

```go
import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

contacts, err := client.Contacts.List(nil)
```

**Rust**

```rust
use emailit::Emailit;

let emailit = Emailit::new("your_api_key");

let contacts = emailit.contacts.list(None).await?;
```

**Java**

```java
import com.emailit.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject contacts = emailit.contacts().list();
```

**.NET**

```csharp
using Emailit;

var emailit = new EmailitClient("your_api_key");

var contacts = emailit.Contacts.List();
```

**Laravel**

```php
use Emailit\Laravel\Facades\Emailit;

$contacts = Emailit::contacts()->list();
```

**cURL**

```bash
curl https://api.emailit.com/v2/contacts \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
```

**cURL**

```bash
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"
```

**200**

```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
}
```

---
Quelle: https://emailit.com/de/docs/api-reference/contacts/list/

## Kontakte gesammelt aktualisieren — POST /contacts/bulk

> Wenden Sie eine Aktion auf bis zu 100 Kontakte gleichzeitig an: löschen, einer Kontaktliste hinzufügen oder daraus entfernen, abmelden oder erneut anmelden.

# 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](/de/docs/api-reference/contacts/delete/). |
| `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

- `action` (string, erforderlich): `delete`, `add_to_audience`, `remove_from_audience`, `unsubscribe` oder `resubscribe`.

- `ids` (string[], erforderlich): Kontakt-IDs (`con_…`), von 1 bis 100. E-Mail-Adressen werden hier nicht akzeptiert. Duplikate werden ignoriert.

- `audience_id` (string): Die ID der Kontaktliste. Erforderlich für `add_to_audience` und `remove_from_audience`.

## Rückgabe

- `object` (string): Immer `contact_bulk`.

- `action` (string): Die ausgeführte Aktion.

- `processed` (integer): Wie viele Kontakte verarbeitet wurden.

- `ids` (string[]): Die IDs der verarbeiteten Kontakte.

**Anfrage** `POST /contacts/bulk`

**Node.js**

```javascript
const response = await fetch('https://api.emailit.com/v2/contacts/bulk', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"action": "add_to_audience", "ids": ["con_4K9kQdrXth7am0TPKvPrR5yd2oo", "con_4KiXIs4xLTcJIAHnKJaLcnMZYh7"], "audience_id": "aud_4KOlh9t2uw5od4qypqCtyrZyDq2"}),
});
const result = await response.json();
```

**Python**

```python
import requests

response = requests.post(
  "https://api.emailit.com/v2/contacts/bulk",
  headers={"Authorization": "Bearer your_api_key"},
  json={"action": "add_to_audience", "ids": ["con_4K9kQdrXth7am0TPKvPrR5yd2oo", "con_4KiXIs4xLTcJIAHnKJaLcnMZYh7"], "audience_id": "aud_4KOlh9t2uw5od4qypqCtyrZyDq2"}
)
result = response.json()
```

**PHP**

```php
$ch = curl_init('https://api.emailit.com/v2/contacts/bulk');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer your_api_key',
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode(['action' => 'add_to_audience', 'ids' => ['con_4K9kQdrXth7am0TPKvPrR5yd2oo', 'con_4KiXIs4xLTcJIAHnKJaLcnMZYh7'], 'audience_id' => 'aud_4KOlh9t2uw5od4qypqCtyrZyDq2']),
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
```

**Ruby**

```ruby
require "net/http"
require "json"

uri = URI("https://api.emailit.com/v2/contacts/bulk")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer your_api_key"
req["Content-Type"] = "application/json"
req.body = { action: "add_to_audience", ids: ["con_4K9kQdrXth7am0TPKvPrR5yd2oo", "con_4KiXIs4xLTcJIAHnKJaLcnMZYh7"], audience_id: "aud_4KOlh9t2uw5od4qypqCtyrZyDq2" }.to_json
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
result = JSON.parse(http.request(req).body)
```

**Go**

```go
payload := strings.NewReader(`{"action": "add_to_audience", "ids": ["con_4K9kQdrXth7am0TPKvPrR5yd2oo", "con_4KiXIs4xLTcJIAHnKJaLcnMZYh7"], "audience_id": "aud_4KOlh9t2uw5od4qypqCtyrZyDq2"}`)
req, _ := http.NewRequest("POST", "https://api.emailit.com/v2/contacts/bulk", payload)
req.Header.Set("Authorization", "Bearer your_api_key")
req.Header.Set("Content-Type", "application/json")

resp, err := http.DefaultClient.Do(req)
if err != nil {
  return err
}
defer resp.Body.Close()
```

**Rust**

```rust
let response = reqwest::Client::new()
    .post("https://api.emailit.com/v2/contacts/bulk")
    .bearer_auth("your_api_key")
    .json(&serde_json::json!({"action": "add_to_audience", "ids": ["con_4K9kQdrXth7am0TPKvPrR5yd2oo", "con_4KiXIs4xLTcJIAHnKJaLcnMZYh7"], "audience_id": "aud_4KOlh9t2uw5od4qypqCtyrZyDq2"}))
    .send()
    .await?;
```

**Java**

```java
import java.net.http.*;
import java.net.URI;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
  .uri(URI.create("https://api.emailit.com/v2/contacts/bulk"))
  .header("Authorization", "Bearer your_api_key")
  .header("Content-Type", "application/json")
  .POST(HttpRequest.BodyPublishers.ofString("{\"action\": \"add_to_audience\", \"ids\": [\"con_4K9kQdrXth7am0TPKvPrR5yd2oo\", \"con_4KiXIs4xLTcJIAHnKJaLcnMZYh7\"], \"audience_id\": \"aud_4KOlh9t2uw5od4qypqCtyrZyDq2\"}"))
  .build();
HttpResponse<String> response = client.send(request,
  HttpResponse.BodyHandlers.ofString());
```

**.NET**

```csharp
using System.Net.Http.Headers;
using System.Text;

var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "your_api_key");

var content = new StringContent(@"{""action"": ""add_to_audience"", ""ids"": [""con_4K9kQdrXth7am0TPKvPrR5yd2oo"", ""con_4KiXIs4xLTcJIAHnKJaLcnMZYh7""], ""audience_id"": ""aud_4KOlh9t2uw5od4qypqCtyrZyDq2""}", Encoding.UTF8, "application/json");
var response = await http.PostAsync("https://api.emailit.com/v2/contacts/bulk", content);
```

**Laravel**

```php
use Illuminate\Support\Facades\Http;

$result = Http::withToken('your_api_key')
  ->post('https://api.emailit.com/v2/contacts/bulk', ['action' => 'add_to_audience', 'ids' => ['con_4K9kQdrXth7am0TPKvPrR5yd2oo', 'con_4KiXIs4xLTcJIAHnKJaLcnMZYh7'], 'audience_id' => 'aud_4KOlh9t2uw5od4qypqCtyrZyDq2'])
  ->json();
```

**cURL**

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

**200**

```json
{
  "object": "contact_bulk",
  "action": "add_to_audience",
  "processed": 2,
  "ids": ["con_4K9kQdrXth7am0TPKvPrR5yd2oo", "con_4KiXIs4xLTcJIAHnKJaLcnMZYh7"]
}
```

**400**

```json
{
  "error": "A maximum of 100 contacts can be updated per request"
}
```

**404**

```json
{
  "error": "One or more contacts were not found",
  "missing": ["con_4K3pZc1Q9nWm2LrT8vYb5Hd0XaE"]
}
```

**422**

```json
{
  "error": "Pro includes 50,000 subscribers per audience.",
  "usage": {
    "used": 50000,
    "limit": 50000,
    "plan": "pro"
  }
}
```

---
Quelle: https://emailit.com/de/docs/api-reference/contacts/bulk/

## Kontakte exportieren — GET /contacts/export

> Laden Sie die Kontakte, die Ihren Filtern entsprechen, als CSV- oder Excel-Datei mit ihren Kontaktlisten und eigenen Feldern herunter. Bis zu 10.000 Kontakte.

# 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](/de/docs/api-reference/contacts/list/), ü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

- `format` (string): `csv` oder `xlsx`.

- `search, audience_id, unsubscribed, sort, order, match, key.condition` (string): Dieselben Parameter wie bei [Kontakte auflisten](/de/docs/api-reference/contacts/list/).

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

**Anfrage** `GET /contacts/export`

**Node.js**

```javascript
import { writeFile } from 'node:fs/promises';

const response = await fetch('https://api.emailit.com/v2/contacts/export?format=csv&audience_id=aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', {
  headers: { Authorization: 'Bearer your_api_key' },
});
await writeFile('contacts.csv', Buffer.from(await response.arrayBuffer()));
```

**Python**

```python
import requests

response = requests.get(
  "https://api.emailit.com/v2/contacts/export?format=csv&audience_id=aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
  headers={"Authorization": "Bearer your_api_key"}
)
with open("contacts.csv", "wb") as f:
    f.write(response.content)
```

**PHP**

```php
$ch = curl_init('https://api.emailit.com/v2/contacts/export?format=csv&audience_id=aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer your_api_key',
  ],
]);
file_put_contents('contacts.csv', curl_exec($ch));
curl_close($ch);
```

**Ruby**

```ruby
require "net/http"

uri = URI("https://api.emailit.com/v2/contacts/export?format=csv&audience_id=aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer your_api_key"
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
File.binwrite("contacts.csv", http.request(req).body)
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.emailit.com/v2/contacts/export?format=csv&audience_id=aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", nil)
req.Header.Set("Authorization", "Bearer your_api_key")

resp, err := http.DefaultClient.Do(req)
if err != nil {
  return err
}
defer resp.Body.Close()

out, _ := os.Create("contacts.csv")
defer out.Close()
io.Copy(out, resp.Body)
```

**Rust**

```rust
let bytes = reqwest::Client::new()
    .get("https://api.emailit.com/v2/contacts/export?format=csv&audience_id=aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2")
    .bearer_auth("your_api_key")
    .send()
    .await?
    .bytes()
    .await?;
std::fs::write("contacts.csv", &bytes)?;
```

**Java**

```java
import java.net.http.*;
import java.net.URI;
import java.nio.file.Path;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
  .uri(URI.create("https://api.emailit.com/v2/contacts/export?format=csv&audience_id=aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2"))
  .header("Authorization", "Bearer your_api_key")
  .GET()
  .build();
client.send(request, HttpResponse.BodyHandlers.ofFile(Path.of("contacts.csv")));
```

**.NET**

```csharp
using System.Net.Http.Headers;

var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "your_api_key");

var bytes = await http.GetByteArrayAsync("https://api.emailit.com/v2/contacts/export?format=csv&audience_id=aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2");
await File.WriteAllBytesAsync("contacts.csv", bytes);
```

**Laravel**

```php
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Storage;

$csv = Http::withToken('your_api_key')
  ->get('https://api.emailit.com/v2/contacts/export?format=csv&audience_id=aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2')
  ->body();
Storage::put('contacts.csv', $csv);
```

**cURL**

```bash
curl "https://api.emailit.com/v2/contacts/export?format=csv&audience_id=aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2" \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -o contacts.csv
```

**200**

```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
```

**400**

```json
{
  "error": "format must be csv or xlsx"
}
```

**422**

```json
{
  "error": "Export is limited to 10000 contacts. Narrow your filters and try again."
}
```

---
Quelle: https://emailit.com/de/docs/api-reference/contacts/export/

## Kontakt löschen — DELETE /contacts/{id}

> Löschen Sie einen Kontakt endgültig und entfernen Sie ihn aus allen Kontaktlisten. Bereits an ihn gesendete E-Mails bleiben in Ihren Logs.

# 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](/de/docs/api-reference/contacts/update/) mit `unsubscribed: true` oder setzen Sie die Adresse auf Ihre [Sperrliste](/de/docs/api-reference/suppressions/create/). Löst für jede Mitgliedschaft `subscriber.deleted` aus, danach `contact.deleted`.

## Pfadparameter

- `id` (string, erforderlich): Die ID des Kontakts (`con_…`) oder seine E-Mail-Adresse, URL-kodiert.

## Rückgabe

- `object` (string): Immer `contact`.

- `id` (string): Die ID des gelöschten Kontakts.

- `email` (string): Die E-Mail-Adresse des Kontakts.

- `deleted` (boolean): Immer `true`.

**Anfrage** `DELETE /contacts/{id}`

**Node.js**

```javascript
import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

await emailit.contacts.delete('con_4Kt4ZXloQR8WGcMsYx8PFCUjokM');
```

**Python**

```python
from emailit import EmailitClient
client = EmailitClient("your_api_key")

client.contacts.delete("con_4Kt4ZXloQR8WGcMsYx8PFCUjokM")
```

**PHP**

```php
$emailit = Emailit::client('your_api_key');

$emailit->contacts()->delete('con_4Kt4ZXloQR8WGcMsYx8PFCUjokM');
```

**Ruby**

```ruby
require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

client.contacts.delete("con_4Kt4ZXloQR8WGcMsYx8PFCUjokM")
```

**Go**

```go
import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

err := client.Contacts.Delete("con_4Kt4ZXloQR8WGcMsYx8PFCUjokM")
```

**Rust**

```rust
use emailit::Emailit;

let emailit = Emailit::new("your_api_key");

emailit.contacts.delete("con_4Kt4ZXloQR8WGcMsYx8PFCUjokM").await?;
```

**Java**

```java
import com.emailit.*;

EmailitClient emailit = new EmailitClient("your_api_key");

emailit.contacts().delete("con_4Kt4ZXloQR8WGcMsYx8PFCUjokM");
```

**.NET**

```csharp
using Emailit;

var emailit = new EmailitClient("your_api_key");

emailit.Contacts.Delete("con_4Kt4ZXloQR8WGcMsYx8PFCUjokM");
```

**Laravel**

```php
use Emailit\Laravel\Facades\Emailit;

Emailit::contacts()->delete('con_4Kt4ZXloQR8WGcMsYx8PFCUjokM');
```

**cURL**

```bash
curl -X DELETE https://api.emailit.com/v2/contacts/con_4Kt4ZXloQR8WGcMsYx8PFCUjokM \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
```

**200**

```json
{
  "object": "contact",
  "id": "con_4Kt4ZXloQR8WGcMsYx8PFCUjokM",
  "email": "alan@example.com",
  "deleted": true
}
```

**404**

```json
{
  "error": "Contact not found"
}
```

---
Quelle: https://emailit.com/de/docs/api-reference/contacts/delete/