Gegevens exporteren via API

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:

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.

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

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

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

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

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

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:

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"

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:

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

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

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

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

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

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

Functionaliteiten

Beperkingen

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:

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