Subscriber Status

Each subscriber has a status that indicates whether newsletters may be received.

Account without channels

Without channels, there is exactly one status per subscriber.

Account
  ├─ Subscriber A (max@example.com)
  │    └─ Status: Active (global)
  │
  ├─ Subscriber B (lisa@example.com)
  │    └─ Status: Unsubscribed (global)
  │
  └─ Newsletter delivery
       └─ Sent to all active subscribers

Account with channels

With channels, each subscriber has one status per channel. For example, a subscriber can be active for a newsletter channel but inactive for an advertising channel.

Account
  ├─ Channel 1: "Product Newsletter"
  ├─ Channel 2: "Blog Updates"
  └─ Channel 3: "Event Invitations"

Subscriber A (max@example.com)
  ├─ Channel 1: Status Active ✓
  ├─ Channel 2: Status Active ✓
  └─ Channel 3: Status Unsubscribed ✗

Subscriber B (lisa@example.com)
  ├─ Channel 1: Status Unsubscribed ✗
  ├─ Channel 2: Status Active ✓
  └─ Channel 3: Status Active ✓

Newsletter sent via Channel 1
  ├─ Subscriber A: Receives newsletter ✓
  └─ Subscriber B: Does not receive newsletter ✗

Status values

There are three basic status values:

Status	Name	Description
1	RECEIVE_READY	Subscriber is ready to receive newsletters.
2	NOT_RECEIVE_READY	Subscriber is not ready yet (e.g. opt-in pending).
3	ARCHIVED	Subscriber is archived and no longer receives newsletters.

Status additions

Each status can have a status addition that specifies the reason in more detail:

Status	Status Addition	Description
1 (RECEIVE_READY)	null	Subscriber is active.
2 (NOT_RECEIVE_READY)	1 = OPTIN_PENDING	Opt-in was requested but not confirmed yet.
2 (NOT_RECEIVE_READY)	2 = NO_OPTIN	No opt-in required (e.g. transactional emails).
2 (NOT_RECEIVE_READY)	3 = TRANSACTION	Transactional emails only.
3 (ARCHIVED)	4 = UNSUBSCRIBED	Subscriber unsubscribed.
3 (ARCHIVED)	5 = HARD_BOUNCE	Email address does not exist (hard bounce).
3 (ARCHIVED)	6 = MANUAL	Archived manually.
3 (ARCHIVED)	7 = COMPLAINED	Spam complaint.
3 (ARCHIVED)	8 = BLACKLIST	Blacklist (manual)

Status Lifecycle

The typical lifecycle of a subscriber:

Newly created
    │
    ├─→ Status 2, Addition 1 (Opt-In pending)
    │       │
    │       └─→ Status 1 (Active) ─────┐
    │                                  │
    └─→ Status 1 (Active without Opt-In) ─┘
                │
                ├─→ Status 3, Addition 4 (Unsubscribed)
                ├─→ Status 3, Addition 5 (Hard Bounce)
                ├─→ Status 3, Addition 6 (Manually archived)
                └─→ Status 3, Addition 7 (Spam complaint)

Examples

Active subscriber

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

Subscriber is active and receives newsletters.

Unsubscribed subscriber

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

Subscriber is archived because they unsubscribed.

Opt-in pending

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

Subscriber was created but still needs to confirm the email address (double opt-in).

Status changes via API

info

Important: Some status changes require special API permissions. For example, an archived unsubscribed subscriber can only be reactivated if the API key has the corresponding permission.

Set status via API

Subscriber status can be set differently depending on account configuration:

Without channels

For accounts without channels, status is set directly on the subscriber object:

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

Request:

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

Example - Unsubscribed subscriber:

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

With channels

For accounts with channels, status is set per channel in the channels array:

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

Retrieve status

Without channels

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
}

With channels

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