# Gegevens exporteren via API

## Introductie

Exporteer alle Zivver-berichten die door je organisatie zijn verzonden en ontvangen voor archiveringsdoeleinden. Met deze methode kun je berichten exporteren via de Zivver API.

Deze exportmethode wordt aanbevolen voor:

- Organisaties met een groot aantal berichten
- Het exporteren van gegevens voor een subset van gebruikers
- Situaties waarin de ZIP-export niet geschikt is

Voor kleinere organisaties met een beperkt aantal berichten raden we aan om de [Zivver WebApp-methode](https://docs.zivver.com/nl/admin/webapp/references/export-data-zivver-message.html) te gebruiken om alle berichten in een ZIP-bestand te exporteren via een Zivver-bericht.

## API-overzicht

De onderstaande secties geven een overzicht van de API-endpoints die worden gebruikt voor het exporteren van gegevens. Nadat de API voor je organisatie is ingeschakeld, kun je deze endpoints gebruiken om je exports te beheren via een script of een API-client (bijvoorbeeld Postman). Alle endpoints vereisen authenticatie via een API-token, die je genereert in het Zivver-adminportaal.

De basis-URL voor alle endpoints is `https://app.zivver.com/api`, en alle verzoeken gebruiken de `GET`-methode.

### /exports/mailbox

Met dit endpoint kun je een lijst ophalen van alle mailboxen binnen je organisatie. Dit endpoint is het startpunt van het exportproces, omdat je moet weten welke mailboxen je wilt exporteren.

Neem de volgende headers op in je verzoek:

- `Authorization: Bearer {API_TOKEN}`
- `Accept: application/json`

### /exports/mailbox/{email_address}

Gebruik dit endpoint om een lijst op te halen van maanden waarvoor er conversaties zijn in een specifieke mailbox. Dit helpt je te bepalen voor welke maanden gegevens beschikbaar zijn voor export.

Neem de volgende headers op in je verzoek:

- `Authorization: Bearer {API_TOKEN}`
- `Accept: application/json`

### /exports/mailbox/{email_address}/{year_month}

Dit endpoint haalt een lijst op van conversaties in een specifieke maand voor een specifieke mailbox. Hiermee kun je bepalen welke conversaties je wilt exporteren.

Neem de volgende headers op in je verzoek:

- `Authorization: Bearer {API_TOKEN}`
- `Accept: application/json`

### /exports/mailbox/{email_address}/{year_month}/{conversationNameKey}

Gebruik dit endpoint om een lijst op te halen van berichten in een conversatie voor een specifieke maand en mailbox. Hiermee kun je de individuele berichten bekijken die onderdeel zijn van de conversatie.

Neem de volgende headers op in je verzoek:

- `Authorization: Bearer {API_TOKEN}`
- `Accept: application/json`

### /exports/mailbox/{email_address}/{year_month}/{conversationNameKey}/{messageNameKey}

Met dit endpoint kun je een specifiek bericht in een conversatie downloaden voor een specifieke maand en mailbox. Het bericht wordt gedownload in EML-formaat, dat geopend kan worden met e-mailclients of geïmporteerd kan worden in andere systemen.

Neem de volgende headers op in je verzoek:

- `Authorization: Bearer {API_TOKEN}`
- `Accept: application/octet-stream`

## Python exportscript

Om het exportproces te vereenvoudigen, bieden we een Python-script dat de API-calls automatiseert en de exportlogica afhandelt. Het script ondersteunt functies zoals filteren op e-mailadres of domein, het hervatten van onderbroken exports en het opnieuw proberen van mislukte downloads. Het script is opgenomen in het exportpakket dat je via de onderstaande link kunt downloaden. Het is ontworpen om via de command line te worden uitgevoerd en kan worden geconfigureerd met een configuratiebestand of command line-argumenten.

### Vereisten

Zorg ervoor dat je aan de volgende vereisten voldoet voordat je begint:

- Python 3.9 of hoger is geïnstalleerd
- [Poetry](https://python-poetry.org/docs/#installation) is geïnstalleerd (aanbevolen)
- API-toegang is ingeschakeld voor je organisatie

### Download

Download het exportpakket, dat het Python-script, een README-bestand en een voorbeeldconfiguratiebestand bevat:

[Download exportscript](https://docs.zivver.com/downloads/admin/webapp/data-export/organization-data-export.zip)

### Configuratie

#### API-token (vereist)

Stel je API-token in als omgevingsvariabele:

```bash
export ZIVVER_API_TOKEN="your-token-here"
```

#### Optie 1: Configuratiebestand

Gebruik een configuratiebestand als je alle instellingen op één plek wilt beheren.

Maak een `config.json`-bestand (zie het voorbeeld in de download):

```json
{
    "api_token": "Please use environment variable ZIVVER_API_TOKEN to set your API token.",
    "output_dir": "./exports",
    "allowed_emails": ["user1@example.com"],
    "allowed_domains": ["example.com"],
    "exclude_emails": ["noreply@example.com"],
    "max_workers": 10,
    "debug": false
}
```

Deze aanpak wordt aanbevolen wanneer:

- Je een herbruikbare configuratie wilt
- Je meerdere exports met dezelfde instellingen uitvoert

#### Optie 2: Command line-argumenten

Gebruik command line-argumenten als je snel eenmalige exports wilt uitvoeren zonder een configuratiebestand te maken.

```bash
organization-data-export \
  --output-dir ./my-exports \
  --allowed-emails user1@example.com,user2@example.com \
  --allowed-domains example.com
```

### Installatie

#### Met Poetry (aanbevolen)

Gebruik deze methode als je het script wilt uitvoeren in een beheerde Python-omgeving waarbij alle afhankelijkheden automatisch worden afgehandeld.

```bash
poetry install
poetry run organization-data-export --help
```

#### Met een buildpakket (wheel)

Gebruik deze methode als je een standaardinstallatie wilt waarbij het commando globaal beschikbaar wordt.

```bash
poetry build
pip install dist/organization_data_export-*.whl
organization-data-export --help
```

### Gebruik

#### Volledige export

Gebruik dit commando om alle beschikbare gegevens te exporteren met een configuratiebestand:

```bash
organization-data-export export --config config.json
```

#### Specifieke e-mailadressen exporteren

Gebruik dit als je alleen gegevens van geselecteerde gebruikers wilt exporteren:

```bash
organization-data-export export --allowed-emails user1@example.com,user2@example.com
```

#### Specifieke domeinen exporteren

Gebruik dit als je alle gebruikers binnen één of meerdere domeinen wilt exporteren:

```bash
organization-data-export export --allowed-domains example.com
```

#### Onderbroken export hervatten

Als een export is onderbroken (bijvoorbeeld door een netwerkprobleem of handmatig stoppen), kun je deze hervatten:

```bash
organization-data-export export --resume
```

#### Mislukte downloads opnieuw proberen

Als sommige bestanden niet zijn gedownload, kun je alleen die bestanden opnieuw proberen:

```bash
organization-data-export retry-failed
```

### Outputstructuur

Geëxporteerde bestanden worden opgeslagen in de volgende structuur:

```gdscript3
exports
└── user@example.com
    └── 2026-01
        └── conversation-id
            ├── message1.eml
            └── message2.eml
```

### Belangrijke aandachtspunten

Grote mailboxen kunnen uren duren om te exporteren. Lange exporttijden zijn normaal.

- De voortgang is niet lineair: sommige mailboxen zijn snel klaar, andere duren veel langer
- Het script verwerkt per mailbox één maand tegelijk
- Het kan lijken alsof de export vastloopt, maar deze is nog steeds bezig
- Rate limiting wordt automatisch afgehandeld

### Functionaliteiten

- Hervatbare exports met `–resume`
- Flexibel filteren op e-mailadres en domein
- Gelijktijdige downloads (instelbaar)
- Automatisch opnieuw proberen bij mislukte downloads
- Logging van mislukte downloads
- Veilige authenticatie via omgevingsvariabelen

### Beperkingen

- API-toegang moet door Zivver worden ingeschakeld om veiligheidsredenen
- Als je het exportscript van Zivver wilt gebruiken, is een Python-installatie vereist
- Het API-token moet per sessie opnieuw worden ingesteld (tenzij permanent geconfigureerd)

## Veelgestelde vragen

**Hoe schakel je de API-endpoints in?** De API-endpoints zijn standaard uitgeschakeld. Maak een supportticket aan om deze voor je organisatie te laten inschakelen.

**Wat te doen als het script halverwege stopt?** Voer hetzelfde commando opnieuw uit en gebruik de `--resume`-flag om verder te gaan waar het was gebleven.

**Sommige bestanden zijn niet gedownload. Hoe probeer je dit opnieuw?** Gebruik het volgende commando om alleen de mislukte downloads opnieuw te proberen:

```bash
organization-data-export retry-failed
```

**Hoe exporteer je gegevens voor alleen specifieke gebruikers?** Gebruik `allowed_emails` om specifieke gebruikers op te nemen, of `allowed_domains` om volledige domeinen op te nemen. Je kunt ook `exclude_emails` gebruiken om specifieke adressen over te slaan.

**Wanneer gebruik je de API-methode in plaats van de ZIP-export?** Gebruik de API-methode voor grote organisaties, gedeeltelijke exports of wanneer de ZIP-export niet geschikt is.

Laatst bijgewerkt op 2026-06-18