# Kontaktlisten API

> Abonnentenlisten für Kampagnen und Anmeldeformulare verwalten.

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

## Kontaktliste erstellen — POST /audiences

> Erstellen Sie eine Kontaktliste: eine Liste von Abonnenten, an die Sie Kampagnen senden und für die Sie Anmeldungen per Formular oder über einen gehosteten Anmeldelink sammeln.

# Kontaktliste erstellen

Erstellt eine leere Kontaktliste.

`POST /audiences`

Erfordert einen API-Schlüssel mit dem Scope `full`. Personen fügen Sie mit [Abonnent hinzufügen](/de/docs/api-reference/audiences/subscribers/add/) hinzu oder indem Sie beim [Erstellen eines Kontakts](/de/docs/api-reference/contacts/create/) die ID der Kontaktliste in `audiences` übergeben. Löst das Event `audience.created` aus. Siehe [Kontaktlisten](/de/docs/audiences/).

## Body-Parameter

- `name` (string, erforderlich): Der Name der Kontaktliste, etwa `Newsletter`. Muss im Workspace eindeutig sein.

## Rückgabe

Gibt `201` mit der neuen Kontaktliste zurück:

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

- `id` (string): Die ID der Kontaktliste.

- `name` (string): Der Name der Kontaktliste.

- `token` (string): Das öffentliche Token für die [gehostete Anmelde-URL](/de/docs/audiences/subscribe-url/) der Kontaktliste.

- `created_at` (string): Zeitpunkt der Erstellung der Kontaktliste.

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

**Anfrage** `POST /audiences`

**Node.js**

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

const audience = await emailit.audiences.create({
  name: 'Newsletter',
});
```

**Python**

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

audience = client.audiences.create({
  "name": "Newsletter"
})
```

**PHP**

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

$audience = $emailit->audiences()->create([
  'name' => 'Newsletter',
]);
```

**Ruby**

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

audience = client.audiences.create(name: "Newsletter")
```

**Go**

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

audience, err := client.Audiences.Create(&emailit.CreateAudienceRequest{
  Name: "Newsletter",
})
```

**Rust**

```rust
use emailit::Emailit;
use emailit::types::CreateAudienceParams;

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

let audience = emailit.audiences.create(
  CreateAudienceParams::new("Newsletter")
).await?;
```

**Java**

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

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject audience = emailit.audiences().create(
  AudienceCreateParams.builder()
    .setName("Newsletter")
    .build()
);
```

**.NET**

```csharp
using Emailit;

var emailit = new EmailitClient("your_api_key");

var audience = emailit.Audiences.Create(new AudienceCreateOptions {
  Name = "Newsletter",
});
```

**Laravel**

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

$audience = Emailit::audiences()->create([
  'name' => 'Newsletter',
]);
```

**cURL**

```bash
curl -X POST https://api.emailit.com/v2/audiences \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Newsletter"}'
```

**201**

```json
{
  "object": "audience",
  "id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
  "name": "Newsletter",
  "token": "4KXUJdXRVlVgbkWQm4GHLy8BleP",
  "created_at": "2026-10-01T10:02:44.613207Z",
  "updated_at": "2026-10-01T10:02:44.613207Z"
}
```

**409**

```json
{
  "error": "Audience with this name already exists",
  "existing": {
    "object": "audience",
    "id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
    "name": "Newsletter",
    "token": "4KXUJdXRVlVgbkWQm4GHLy8BleP",
    "subscribers_count": 0,
    "created_at": "2026-10-01T10:02:44.000000Z",
    "updated_at": "2026-10-01T10:02:44.000000Z"
  }
}
```

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

## Kontaktliste abrufen — GET /audiences/{id}

> Rufen Sie eine Kontaktliste per ID oder Name ab, mit der Anzahl ihrer Abonnenten, dem Abonnentenlimit Ihres Tarifs und dem Token für ihre gehostete Anmelde-URL.

# Kontaktliste abrufen

Ruft eine Kontaktliste mit der Anzahl ihrer Abonnenten und ihrem öffentlichen Token ab.

`GET /audiences/{id}`

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

## Pfadparameter

- `id` (string, erforderlich): Die ID der Kontaktliste (`aud_…`) oder ihr exakter Name, URL-kodiert.

## Rückgabe

Gibt das Kontaktlisten-Objekt zurück.

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

- `id` (string): Die ID der Kontaktliste.

- `name` (string): Der Name der Kontaktliste.

- `token` (string): Das öffentliche Token für die [gehostete Anmelde-URL](/de/docs/audiences/subscribe-url/) der Kontaktliste. Behandeln Sie es als öffentlich: Wer es kennt, kann sich bei der Kontaktliste anmelden.

- `subscribers_count` (integer): Wie viele Kontakte in der Kontaktliste sind, abgemeldete eingeschlossen.

- `usage` (object): `used` (dieselbe Anzahl), `limit` (die maximale Anzahl Abonnenten pro Kontaktliste in Ihrem Tarif oder `null` ohne Limit) und `plan`. Siehe [Limits](/de/docs/limits/).

- `created_at` (string): Zeitpunkt der Erstellung der Kontaktliste.

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

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

**Node.js**

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

const audience = await emailit.audiences.get('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2');
```

**Python**

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

audience = client.audiences.get("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2")
```

**PHP**

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

$audience = $emailit->audiences()->get('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2');
```

**Ruby**

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

audience = client.audiences.get("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2")
```

**Go**

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

audience, err := client.Audiences.Get("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2")
```

**Rust**

```rust
use emailit::Emailit;

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

let audience = emailit.audiences.get("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2").await?;
```

**Java**

```java
import com.emailit.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject audience = emailit.audiences().get("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2");
```

**.NET**

```csharp
using Emailit;

var emailit = new EmailitClient("your_api_key");

var audience = emailit.Audiences.Get("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2");
```

**Laravel**

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

$audience = Emailit::audiences()->get('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2');
```

**cURL**

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

**200**

```json
{
  "object": "audience",
  "id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
  "name": "Newsletter",
  "token": "4KXUJdXRVlVgbkWQm4GHLy8BleP",
  "subscribers_count": 1284,
  "usage": {
    "used": 1284,
    "limit": 50000,
    "plan": "pro"
  },
  "created_at": "2026-10-01T10:02:44.000000Z",
  "updated_at": "2026-10-01T10:02:44.000000Z"
}
```

**404**

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

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

## Kontaktliste aktualisieren — POST /audiences/{id}

> Benennen Sie eine Kontaktliste um. Ihre ID, ihr öffentliches Token und ihre Abonnenten bleiben gleich.

# Kontaktliste aktualisieren

Benennt eine Kontaktliste um.

`POST /audiences/{id}`

Erfordert einen API-Schlüssel mit dem Scope `full`. ID, Token und Abonnenten ändern sich nicht. Löst das Event `audience.updated` aus.

## Pfadparameter

- `id` (string, erforderlich): Die ID der Kontaktliste oder ihr aktueller Name.

## Body-Parameter

- `name` (string, erforderlich): Der neue Name. Muss im Workspace eindeutig sein.

## Rückgabe

Gibt die Kontaktliste mit `object`, `id`, `name`, `token`, `subscribers_count`, `created_at` und `updated_at` zurück. In dieser Antwort ist `subscribers_count` immer `0`; die tatsächliche Anzahl liefert [Kontaktliste abrufen](/de/docs/api-reference/audiences/get/).

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

**Node.js**

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

const audience = await emailit.audiences.update('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', {
  name: 'Weekly newsletter',
});
```

**Python**

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

audience = client.audiences.update("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", {
  "name": "Weekly newsletter"
})
```

**PHP**

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

$audience = $emailit->audiences()->update('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', [
  'name' => 'Weekly newsletter',
]);
```

**Ruby**

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

audience = client.audiences.update("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", name: "Weekly newsletter")
```

**Go**

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

audience, err := client.Audiences.Update("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", &emailit.UpdateAudienceRequest{
  Name: "Weekly newsletter",
})
```

**Rust**

```rust
use emailit::Emailit;
use emailit::types::UpdateAudienceParams;

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

let audience = emailit.audiences.update("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", UpdateAudienceParams {
  name: Some("Weekly newsletter".into()),
  ..Default::default()
}).await?;
```

**Java**

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

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject audience = emailit.audiences().update("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
  AudienceUpdateParams.builder()
    .setName("Weekly newsletter")
    .build()
);
```

**.NET**

```csharp
using Emailit;

var emailit = new EmailitClient("your_api_key");

var audience = emailit.Audiences.Update("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", new AudienceUpdateOptions {
  Name = "Weekly newsletter",
});
```

**Laravel**

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

$audience = Emailit::audiences()->update('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', [
  'name' => 'Weekly newsletter',
]);
```

**cURL**

```bash
curl -X POST https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2 \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Weekly newsletter"}'
```

**200**

```json
{
  "object": "audience",
  "id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
  "name": "Weekly newsletter",
  "token": "4KXUJdXRVlVgbkWQm4GHLy8BleP",
  "subscribers_count": 0,
  "created_at": "2026-10-01T10:02:44.000000Z",
  "updated_at": "2026-10-01T14:31:09.000000Z"
}
```

**400**

```json
{
  "error": "No valid fields provided for update. Provide at least one of: name"
}
```

**404**

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

**409**

```json
{
  "error": "Another audience with this name already exists"
}
```

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

## Kontaktlisten auflisten — GET /audiences

> Listen Sie die Kontaktlisten eines Workspace mit Abonnentenzahlen und Tariflimits auf, die neuesten zuerst, mit Suche, Filtern und Sortierung.

# Kontaktlisten auflisten

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

`GET /audiences`

Erfordert einen API-Schlüssel mit dem Scope `full`. Die Listeneinträge enthalten nicht das `token` der Kontaktliste; dafür nutzen Sie [Kontaktliste abrufen](/de/docs/api-reference/audiences/get/).

## Query-Parameter

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

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

- `search` (string): Abgleich mit dem Namen der Kontaktliste, ohne Beachtung der Groß-/Kleinschreibung.

- `match` (string): `all` oder `or`. Wie die Filter unten kombiniert werden.

- `order` (string): `name` oder `created_at`.

- `direction` (string): `asc` oder `desc`.

## Filter

Fügen Sie Filter als `key.condition=value` hinzu, zum Beispiel `name.contains=news`. Siehe [Filtern und Sortieren](/de/docs/api-reference/filtering/).

| Schlüssel | Typ |
| --- | --- |
| `name` | string |
| `created_at` | date |

## Rückgabe

- `data` (object[]): Die Kontaktlisten auf dieser Seite, jeweils mit `object`, `id`, `name`, `subscribers_count`, `usage`, `created_at` und `updated_at`. Siehe [Kontaktliste abrufen](/de/docs/api-reference/audiences/get/).

- `total_records` (integer): Die Anzahl der Kontaktlisten im Workspace.

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

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

**Anfrage** `GET /audiences`

**Node.js**

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

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

**Python**

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

audiences = client.audiences.list()
```

**PHP**

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

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

**Ruby**

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

audiences = client.audiences.list
```

**Go**

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

audiences, err := client.Audiences.List(nil)
```

**Rust**

```rust
use emailit::Emailit;

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

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

**Java**

```java
import com.emailit.*;

EmailitClient emailit = new EmailitClient("your_api_key");

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

**.NET**

```csharp
using Emailit;

var emailit = new EmailitClient("your_api_key");

var audiences = emailit.Audiences.List();
```

**Laravel**

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

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

**cURL**

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

**200**

```json
{
  "data": [
    {
      "object": "audience",
      "id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
      "name": "Newsletter",
      "subscribers_count": 1284,
      "usage": {
        "used": 1284,
        "limit": 50000,
        "plan": "pro"
      },
      "created_at": "2026-10-01T10:02:44.000000Z",
      "updated_at": "2026-10-01T10:02:44.000000Z"
    },
    {
      "object": "audience",
      "id": "aud_4KOlh9t2uw5od4qypqCtyrZyDq2",
      "name": "Customers",
      "subscribers_count": 312,
      "usage": {
        "used": 312,
        "limit": 50000,
        "plan": "pro"
      },
      "created_at": "2026-09-20T16:45:10.000000Z",
      "updated_at": "2026-09-20T16:45:10.000000Z"
    }
  ],
  "total_records": 2,
  "next_page_url": null,
  "previous_page_url": null
}
```

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

## Kontaktliste löschen — DELETE /audiences/{id}

> Löschen Sie eine Kontaktliste mit allen Mitgliedschaften ihrer Abonnenten endgültig. Die Kontakte selbst bleiben in Ihrem Workspace.

# Kontaktliste löschen

Löscht eine Kontaktliste endgültig und entfernt alle Abonnenten daraus.

`DELETE /audiences/{id}`

Erfordert einen API-Schlüssel mit dem Scope `full`. Die Mitgliedschaften der Abonnenten werden mit der Kontaktliste gelöscht, die [Kontakte](/de/docs/api-reference/contacts/) bleiben aber in Ihrem Workspace und in ihren anderen Kontaktlisten. Die gehostete Anmelde-URL der Kontaktliste funktioniert nicht mehr. Löst das Event `audience.deleted` aus. Für die entfernten Mitgliedschaften werden keine `subscriber.deleted`-Events gesendet.

## Pfadparameter

- `id` (string, erforderlich): Die ID der Kontaktliste oder ihr Name.

## Rückgabe

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

- `id` (string): Die ID der gelöschten Kontaktliste.

- `name` (string): Der Name der Kontaktliste.

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

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

**Node.js**

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

await emailit.audiences.delete('aud_4KOlh9t2uw5od4qypqCtyrZyDq2');
```

**Python**

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

client.audiences.delete("aud_4KOlh9t2uw5od4qypqCtyrZyDq2")
```

**PHP**

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

$emailit->audiences()->delete('aud_4KOlh9t2uw5od4qypqCtyrZyDq2');
```

**Ruby**

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

client.audiences.delete("aud_4KOlh9t2uw5od4qypqCtyrZyDq2")
```

**Go**

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

err := client.Audiences.Delete("aud_4KOlh9t2uw5od4qypqCtyrZyDq2")
```

**Rust**

```rust
use emailit::Emailit;

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

emailit.audiences.delete("aud_4KOlh9t2uw5od4qypqCtyrZyDq2").await?;
```

**Java**

```java
import com.emailit.*;

EmailitClient emailit = new EmailitClient("your_api_key");

emailit.audiences().delete("aud_4KOlh9t2uw5od4qypqCtyrZyDq2");
```

**.NET**

```csharp
using Emailit;

var emailit = new EmailitClient("your_api_key");

emailit.Audiences.Delete("aud_4KOlh9t2uw5od4qypqCtyrZyDq2");
```

**Laravel**

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

Emailit::audiences()->delete('aud_4KOlh9t2uw5od4qypqCtyrZyDq2');
```

**cURL**

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

**200**

```json
{
  "object": "audience",
  "id": "aud_4KOlh9t2uw5od4qypqCtyrZyDq2",
  "name": "Customers",
  "deleted": true
}
```

**404**

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

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