Lädt Einträge aus der Blacklist — Nummern, die sich vom Empfang von Nachrichten abgemeldet haben oder per Import bzw. über die API auf die Blacklist gesetzt wurden.

## API-URL

Die URL, an die die HTTP-Anfragen gesendet werden:

```url
https://portal.bulkgate.com/api/1.0/black-list/load
```

> [!NOTE]
> Erreicht die Anfrage ihr Ziel nicht, wiederholen Sie sie auf dem [Backup-Server](https://www.bulkgate.com/de/dokumentation/api-verwaltung-und-tokens/backup-server/) `backup1.bulkgate.com`.

## Unterstützte HTTP-Methoden

- `POST` - `application/json`

```http
POST /api/1.0/black-list/load HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
```

> [!NOTE]
> Für die API gilt ein Kontingent von `20` Anfragen pro Tag.

## Parametertabelle

| PARAMETERNAME     | WERT                                                                                                                                                              | PFLICHT                 | STANDARDWERT   |
|:------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------|:------------------------|:---------------|
| application_id    | [Application ID](https://www.bulkgate.com/de/dokumentation/api-verwaltung-und-tokens/api-verwaltung/)                                                                                                                     | **Ja**                  | -              | 
| application_token | [Authentifizierungstoken der Anwendung](https://www.bulkgate.com/de/dokumentation/api-verwaltung-und-tokens/api-tokens/)	                                                                                                      | **Ja**                  | -              |
| from              | Wählt Einträge **ab** einem bestimmten Datum aus. Akzeptiert das Format [Unix-Zeitstempel](https://en.wikipedia.org/wiki/Unix_time) oder [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). | **Ja**                  | -              |
| to                | Wählt Einträge **bis** zu einem bestimmten Datum aus. Akzeptiert das Format [Unix-Zeitstempel](https://en.wikipedia.org/wiki/Unix_time) oder [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).	 | Nein                    | `now`          |
| campaign_id       | Wählt nur Einträge einer bestimmten Kampagne aus                                                                                                                  | Nein                    | -              |
| wallet            | Wählt nur Einträge einer bestimmten Wallet aus                                                                                                                    | Nein                    | Standard-Wallet |

> [!NOTE]
> Der maximale Zeitraum zwischen `from` und `to` beträgt 30 Tage.

## Beispiel einer Anfrage

```http-json
POST /api/1.0/black-list/load HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json

{
  "application_id": 451,
  "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",
  "campaign_id": "id-bulkgate-000001",
  "wallet": "bg1905014138000023",
  "from": "2018-05-14T18:30:00-01:00",
  "to": "2018-05-15T18:30:00-01:00"
}
```

## Antwort

**Bei Erfolg:**

```json
{
    "data": [
        {
            "key": "198668",
            "id": "198668",
            "wallet": "bg1905014138000023",
            "phone_number": "420777777777",
            "country": "cz",
            "type": "black-list",
            "created": "2018-11-21T15:30:31+01:00",
            "modified": null,
            "source": "web",
            "source_key": null,
            "reason": "Ich möchte keine Werbenachrichten erhalten.",
            "campaign_id": "id-bulkgate-000001",
            "application_id": 451,
            "channel": null,
            "tag": null,
            "contact": null
        },
        {
            "key": "198667",
            "id": "198667",
            "wallet": "bg1905014138000023",
            "phone_number": "420777777778",
            "country": "cz",
            "type": "black-list",
            "created": "2018-11-21T15:30:35+01:00",
            "modified": null,
            "source": "import",
            "source_key": "import.csv",
            "reason": null,
            "campaign_id": null,
            "application_id": 451,
            "channel": null,
            "tag": null,
            "contact": null
        }
    ]
}
```

Dabei gilt:

- **key** und **id** sind die Kennung des Eintrags (derselbe Wert)
- **phone_number** ist die Nummer im internationalen Format
- **type** ist entweder `black-list` oder `opt-out`
- **created** und **modified** sind die Zeitpunkte, zu denen der Eintrag erstellt und zuletzt geändert wurde, im Format [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)
- **source** gibt an, wie die Nummer auf die Blacklist gelangt ist — `web`, `import`, `api`, `manual` oder `auto`
- **source_key** ist die Kennung der Gruppe, mit der die Nummer hinzugefügt wurde. Bei Einträgen mit `source` = `import` enthält es den Namen der importierten Datei.
- **reason** ist der Grund, der beim Setzen der Nummer auf die Blacklist angegeben wurde

**Im Fehlerfall:**

```json
{
    "type": "invalid_wallet",
    "code": 400,
    "error": "Invalid wallet",
    "detail": null
}
```

```json
{
    "type": "invalid_input_parameters",
    "code": 400,
    "error": "Invalid input parameters",
    "detail": null
}
```

```json
{
    "type": "maximal_date_range_is_30_days",
    "code": 400,
    "error": "Maximal date range is 30 days",
    "detail": null
}
```

```json
{
    "type": "the_daily_quota_has_been_exceeded",
    "code": 400,
    "error": "The daily quota has been exceeded",
    "detail": null
}
```

Dabei gilt:

- **type** und **error** (Beschreibung des Fehlers) finden Sie in der [Tabelle der Fehlertypen](https://www.bulkgate.com/de/dokumentation/api-verwaltung-und-tokens/api-fehlertypen/)
- **code** ist der HTTP-Fehlercode
- **detail** enthält zusätzliche Informationen zum Fehler

### Fehlertypen der Blacklist API

Neben den [allgemeinen Typen](https://www.bulkgate.com/de/dokumentation/api-verwaltung-und-tokens/api-fehlertypen/) gibt die Blacklist API eigene Fehlertypen zurück:

| TYP                               | WANN ER AUFTRITT                                               |
|:----------------------------------|:-----------------------------------------------------------------|
| `invalid_wallet`                  | Die angegebene Wallet existiert nicht oder Sie haben keinen Zugriff darauf. |
| `invalid_input_parameters`        | `from` fehlt, hat ein ungültiges Format oder ist nicht älter als `to`. |
| `maximal_date_range_is_30_days`   | Der Zeitraum zwischen `from` und `to` ist länger als 30 Tage.  |
| `the_daily_quota_has_been_exceeded`| Das Anfragekontingent ist aufgebraucht.                       |