Empfänger-Status

Jeder Empfänger hat einen Status, der angibt, ob er Newsletter empfangen darf.

Account ohne Kanäle

Ohne Kanäle gibt es genau einen Status pro Empfänger.

Account
  ├─ Empfänger A (max@example.com)
  │    └─ Status: Aktiv (global)
  │
  ├─ Empfänger B (lisa@example.com)
  │    └─ Status: Abgemeldet (global)
  │
  └─ Newsletter-Versand
       └─ Geht an alle aktiven Empfänger

Account mit Kanälen

Mit Kanälen hat jeder Empfänger einen Status pro Kanal. So kann ein Empfänger z.B. für den Newsletter-Kanal aktiv sein, aber für den Werbe-Kanal inaktiv.

Account
  ├─ Kanal 1: "Produkt-Newsletter"
  ├─ Kanal 2: "Blog-Updates"
  └─ Kanal 3: "Event-Einladungen"

Empfänger A (max@example.com)
  ├─ Kanal 1: Status Aktiv ✓
  ├─ Kanal 2: Status Aktiv ✓
  └─ Kanal 3: Status Abgemeldet ✗

Empfänger B (lisa@example.com)
  ├─ Kanal 1: Status Abgemeldet ✗
  ├─ Kanal 2: Status Aktiv ✓
  └─ Kanal 3: Status Aktiv ✓

Newsletter-Versand über Kanal 1
  ├─ Empfänger A: Erhält Newsletter ✓
  └─ Empfänger B: Erhält keinen Newsletter ✗

Status-Werte

Es gibt drei grundlegende Status-Werte:

Status	Name	Beschreibung
1	RECEIVE_READY	Empfänger ist bereit, Newsletter zu empfangen.
2	NOT_RECEIVE_READY	Empfänger ist noch nicht bereit (z.B. Opt-In ausstehend).
3	ARCHIVED	Empfänger ist archiviert und erhält keine Newsletter mehr.

Status-Additions

Jeder Status kann eine Status-Addition besitzen, die den Grund für den Status präzisiert:

Status	Status-Addition	Beschreibung
1 (RECEIVE_READY)	null	Empfänger ist aktiv.
2 (NOT_RECEIVE_READY)	1 = OPTIN_PENDING	Opt-In wurde angefordert, aber noch nicht bestätigt.
2 (NOT_RECEIVE_READY)	2 = NO_OPTIN	Kein Opt-In erforderlich (z.B. Transaktionsmails).
2 (NOT_RECEIVE_READY)	3 = TRANSACTION	Nur für Transaktionsmails.
3 (ARCHIVED)	4 = UNSUBSCRIBED	Empfänger hat sich abgemeldet.
3 (ARCHIVED)	5 = HARD_BOUNCE	E-Mail-Adresse existiert nicht (Hard Bounce).
3 (ARCHIVED)	6 = MANUAL	Manuell archiviert.
3 (ARCHIVED)	7 = COMPLAINED	Spam-Beschwerde (Complaint).
3 (ARCHIVED)	8 = BLACKLIST	Blacklist (manuell)

Status-Lifecycle

Der typische Lebenszyklus eines Empfängers:

Neu erstellt
    │
    ├─→ Status 2, Addition 1 (Opt-In ausstehend)
    │       │
    │       └─→ Status 1 (Aktiv) ─────┐
    │                                  │
    └─→ Status 1 (Aktiv ohne Opt-In) ─┘
                │
                ├─→ Status 3, Addition 4 (Abgemeldet)
                ├─→ Status 3, Addition 5 (Hard Bounce)
                ├─→ Status 3, Addition 6 (Manuell archiviert)
                └─→ Status 3, Addition 7 (Spam-Beschwerde)

Beispiele

Aktiver Empfänger

{
  "status": 1,
  "statusAddition": null
}

Empfänger ist aktiv und erhält Newsletter.

Abgemeldeter Empfänger

{
  "status": 3,
  "statusAddition": 4
}

Empfänger ist archiviert, weil er sich abgemeldet hat.

Opt-In ausstehend

{
  "status": 2,
  "statusAddition": 1
}

Empfänger wurde angelegt, muss aber noch seine E-Mail-Adresse bestätigen (Double Opt-In).

Status-Änderungen über API

info

Wichtig: Bestimmte Status-Änderungen erfordern spezielle API-Rechte. Zum Beispiel kann ein archivierter, abgemeldeter Empfänger nur reaktiviert werden, wenn der API-Key das entsprechende Recht besitzt.

Status über API setzen

Der Status eines Empfängers kann je nach Account-Konfiguration unterschiedlich gesetzt werden:

Ohne Kanäle

Bei Accounts ohne Kanäle wird der Status direkt auf dem Empfänger-Objekt gesetzt:

POST /subscribers
PUT /subscribers/{id}
PUT /subscribers/multiple
POST /subscribers/upsert

Request:

{
    "email": "mail@example.com",
    "status": 1,
    "statusAddition": null
}

Beispiel - Abgemeldeter Empfänger:

{
    "email": "mail@example.com",
    "status": 3,
    "statusAddition": 4
}

Mit Kanälen

Bei Accounts mit Kanälen wird der Status pro Kanal im channels-Array gesetzt:

POST /subscribers
PUT /subscribers/{id}
PUT /subscribers/multiple
POST /subscribers/upsert

Request:

{
    "email": "mail@example.com",
    "channels": [
        {
            "id": 1,
            "status": 1,
            "statusAddition": null
        },
        {
            "id": 2,
            "status": 3,
            "statusAddition": 4
        }
    ]
}

Status abrufen

Ohne Kanäle

GET /subscribers/{id}

Response:

{
    "objectType": "Subscriber",
    "id": 1,
    "email": "mail@example.com",
    "status": 1,
    "statusAddition": null,
    "optinAt": "2024-01-15 10:30:00",
    "optoutAt": null
}

Mit Kanälen

GET /subscribers/{id}?include=channels

Response:

{
    "objectType": "Subscriber",
    "id": 1,
    "email": "mail@example.com",
    "channels": {
        "data": [
            {
                "objectType": "Channel",
                "id": 1,
                "isDefault": true,
                "status": 1,
                "statusAddition": null,
                "optinAt": "2024-01-15 10:30:00",
                "optinIp": "192.168.1.1",
                "optoutAt": null,
                "optoutIp": null,
                "translations": {
                    "de": {
                        "name": "Newsletter"
                    }
                }
            }
        ]
    }
}