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 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.

Opmerking

De API-endpoints zijn standaard uitgeschakeld. Maak een supportticket aan om deze voor je organisatie te laten inschakelen.

/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 is geïnstalleerd (aanbevolen)
• API-toegang is ingeschakeld voor je organisatie

Opmerking

De API-endpoints zijn standaard uitgeschakeld. Maak een supportticket aan om deze voor je organisatie te laten inschakelen.

Download

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

Download exportscript

Configuratie

API-token (vereist)

Stel je API-token in als omgevingsvariabele:

export ZIVVER_API_TOKEN="your-token-here"

Opmerking

Om veiligheidsredenen raden we aan om het API-token in te stellen via de ZIVVER_API_TOKEN-omgevingsvariabele en deze niet op te slaan in het configuratiebestand.

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):

{
    "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.

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

Deze aanpak is handig wanneer:

• Je specifieke instellingen wilt overschrijven
• Je aan het testen bent of ad-hoc exports uitvoert

Opmerking

Wanneer je zowel allowed_emails als allowed_domains gebruikt, worden e-mailadressen die aan één van beide voorwaarden voldoen opgenomen (OR-logica).

Installatie

Met Poetry (aanbevolen)

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

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

Dit zal:

• Alle benodigde afhankelijkheden installeren
• Je in staat stellen het script uit te voeren met poetry run

Met een buildpakket (wheel)

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

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

Dit zal:

• Het pakket bouwen
• Het installeren zodat je organization-data-export direct kunt uitvoeren

Gebruik

Volledige export

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

organization-data-export export --config config.json

Specifieke e-mailadressen exporteren

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

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:

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:

organization-data-export export --resume

Dit gaat verder waar de vorige run is gestopt zonder bestaande gegevens opnieuw te downloaden.

Mislukte downloads opnieuw proberen

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

organization-data-export retry-failed

Outputstructuur

Geëxporteerde bestanden worden opgeslagen in de volgende structuur:

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

Belangrijke aandachtspunten

Waarschuwing

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

organization-data-export retry-failed