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

Dit is het enige lijst-endpoint met paginering. De andere lijst-endpoints geven alle items in één respons terug. Een respons bevat maximaal 100 conversaties in items. Als er meer conversaties zijn, bevat de respons ook een cursor-waarde:

• Om de volgende pagina op te halen, geef je de cursor-waarde ongewijzigd mee als cursor-queryparameter in het volgende verzoek. De waarde is ondoorzichtig, dus probeer deze niet te interpreteren of aan te passen.
• Als een respons geen cursor-waarde bevat, heb je de laatste pagina bereikt.
• De paginagrootte is vast op 100 conversaties en kan niet worden aangepast.
• Een ongeldige cursor-waarde geeft status 400 terug met Invalid cursor parameter.
• Een maand in een geldig yyyyMM-formaat zonder conversaties geeft {"items": []} terug.

Het eerste verzoek geeft bijvoorbeeld 100 conversaties en een cursor-waarde terug. Het tweede verzoek, met die waarde, geeft de resterende conversaties terug en geen cursor, dus dit is de laatste pagina:

GET /exports/mailbox/jan@example.com/202603
GET /exports/mailbox/jan@example.com/202603?cursor=7f3e9c2a-...

/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

Afleveringsbewijzen

Je kunt ook het afleveringsbewijs van elk bericht exporteren als PDF. Het rapport toont wanneer een bericht is verzonden, naar wie het is verzonden en wat er per ontvanger mee is gebeurd, zoals of het is afgeleverd en geopend. Gebruik het rapport om bewijs van aflevering samen met het bericht te archiveren, bijvoorbeeld in een documentbeheersysteem.

Vereisten voor afleveringsbewijzen

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

• API-toegang is ingeschakeld voor je organisatie (zie API-overzicht)
• Het afleveringsbewijs is ingeschakeld voor je organisatie. Dit gebeurt apart van de API-endpoints, dus maak een supportticket aan om het voor je organisatie te laten inschakelen.
• Het API-token heeft de export:read-permissie. Alle export-endpoints vereisen deze permissie en het /pod-endpoint heeft geen extra tokenpermissie nodig.

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

Met dit endpoint download je het afleveringsbewijs van een specifiek bericht als PDF-bestand. Het endpoint gebruikt hetzelfde pad als het endpoint waarmee je het bericht downloadt, gevolgd door /pod. Gebruik voor elk deel van het pad de waarden die de andere export-endpoints teruggeven:

Neem de volgende headers op in je verzoek:

• Authorization: Bearer {API_TOKEN}
• Accept: application/pdf
• Accept-Language: {language} (optioneel, zie Taal van het rapport)

Alleen het berichtnummer aan het begin van messageNameKey wordt gebruikt om het bericht te vinden: minimaal vier cijfers gevolgd door een underscore, zoals 0001_. De rest van de naam kan veranderen nadat je de lijst hebt opgehaald, bijvoorbeeld wanneer een bericht wordt ingetrokken. Een berichtnaam die je eerder hebt opgeslagen, blijft geldig.

Taal van het rapport

De taal van het rapport volgt de Accept-Language-header. De volgende talen worden ondersteund:

Regionale varianten worden ondersteund, bijvoorbeeld de-DE geeft een Duits rapport. Als de header ontbreekt of geen ondersteunde taal bevat, is het rapport in het Engels.

Leveringsrapporten en ontvangstbewijzen

Het type rapport hangt af van de rol van de eigenaar van de mailbox voor het opgevraagde bericht. Je kunt het type niet zelf kiezen.

De berichtgegevens in beide rapporten zijn het bericht-ID, de afzender, de ontvangers, het onderwerp, de namen van de bijlagen en het tijdstip van verzending. De header van het rapport toont het adres van de mailbox en het tijdstip waarop het rapport is gegenereerd.

Het type wordt per bericht bepaald. In een conversatie waarin de eigenaar van de mailbox het eerste bericht verzond en een antwoord ontving, heeft het eerste bericht een leveringsrapport en het antwoord een ontvangstbewijs.

Om te bewijzen dat een bericht is verzonden en afgeleverd, vraag je het rapport op vanuit de mailbox van de afzender. Om te bewijzen dat een bericht is ontvangen, vraag je het rapport op vanuit de mailbox van de ontvanger.

Respons

Een geslaagd verzoek geeft status 200 terug met het rapport als PDF-bestand (Content-Type: application/pdf). De bestandsnaam staat in de Content-Disposition-header:

Content-Disposition: attachment; filename="delivery_report_0001_20260115T093000Z_Quarterly_report.pdf"

De bestandsnaam bestaat uit:

• Het type rapport: delivery_report of receipt_report (zie Leveringsrapporten en ontvangstbewijzen)
• De berichtnaam zonder .eml en zonder markeringen zoals REVOKED
• Het onderwerp van de conversatie. Andere tekens dan A-Z, a-z, 0-9, ., _ en - worden vervangen door _, en het onderwerp wordt ingekort tot 30 tekens. Het onderwerp wordt weggelaten als er geen bruikbare tekens overblijven.

Het rapport wordt gegenereerd op het moment dat je het opvraagt en is gebaseerd op de afleverinformatie die op dat moment beschikbaar is. Als je hetzelfde rapport later opnieuw opvraagt, kan het nieuwe gebeurtenissen bevatten, bijvoorbeeld een ontvanger die het bericht inmiddels heeft geopend. Sla de gedownloade PDF op als je een vaste kopie nodig hebt.

Bijzondere situaties

Ingetrokken en verwijderde berichten

Het rapport blijft beschikbaar nadat een bericht is ingetrokken of verwijderd.

• Wanneer de eigenaar van de mailbox geen toegang meer heeft tot het bericht, bevat de berichtnaam in de lijst REVOKED of DELETED, bijvoorbeeld 0001_REVOKED_20260115T093000Z.eml. Berichten die de eigenaar van de mailbox zelf heeft ingetrokken of verwijderd, behouden hun oorspronkelijke naam.
• Zowel de nieuwe naam als de naam die je eerder hebt opgeslagen, geven hetzelfde rapport terug, met dezelfde bestandsnaam.
• Het rapport toont nog steeds de namen van de bijlagen, ook al kan het bericht zelf niet meer worden geëxporteerd.

Doorgestuurde berichten

Wanneer een bericht wordt doorgestuurd, wordt een kopie van het oorspronkelijke bericht toegevoegd aan de nieuwe conversatie. In de lijst met berichten is de kopie gemarkeerd met FORWARDED, bijvoorbeeld 0001_FORWARDED_20260114T080000Z.eml.

• Een doorgestuurde kopie heeft geen eigen rapport. Een verzoek geeft status 404 terug met No delivery events are recorded for this message.
• Om het rapport van het doorsturen zelf op te halen, vraag je het bericht op zonder de markering FORWARDED, bijvoorbeeld 0002_20260115T093000Z.eml.
• Om het rapport van het oorspronkelijke bericht op te halen, vraag je het op in de conversatie waarin het oorspronkelijk is verzonden.

Ontoegankelijke conversaties

Een conversatie is ontoegankelijk wanneer de inhoud niet meer kan worden ontsleuteld voor de eigenaar van de mailbox, bijvoorbeeld na een wachtwoordreset zonder herstelcode. De naam van de conversatie eindigt op _INACCESSIBLE en de lijst met berichten is leeg. Een verzoek om een rapport in deze conversatie geeft status 404 terug met Conversation not found.

Fouten

Als een verzoek mislukt, bevat de body van de respons een korte foutmelding in platte tekst. De Content-Type-header van een foutrespons is nog steeds application/pdf, controleer daarom altijd de statuscode voordat je de respons als PDF-bestand verwerkt.

Rapporten exporteren met een script

Om de rapporten van alle berichten te exporteren, volg je dezelfde stappen als voor de berichtexport (zie API-overzicht) en vraag je het rapport van elk bericht op met het /pod-endpoint.

Houd rekening met het volgende:

• Status 404 met No delivery events are recorded for this message wordt verwacht voor doorgestuurde berichten. Behandel dit als “geen rapport beschikbaar” in plaats van een mislukte download.
• Dit endpoint deelt zijn capaciteit met het endpoint voor het downloaden van berichten. Wacht bij status 503 het aantal seconden in de Retry-After-header af voordat je het opnieuw probeert.

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 exporteren van afleveringsbewijzen, 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,
    "content": ["eml", "pod"],
    "language": "nl"
}

Kies met content wat het script per bericht downloadt: eml voor het bericht, pod voor het afleveringsbewijs, of eml,pod voor beide. De standaardwaarde is ["eml"]. Stel met language de taal van de rapporten in. Zie Rapporten exporteren met het Python-script.

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

Afleveringsbewijzen exporteren

Gebruik dit als je het afleveringsbewijs van elk bericht wilt exporteren, met of zonder de berichten:

organization-data-export export --content eml,pod --language nl

Zie Rapporten exporteren met het Python-script voor meer informatie.

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

Het log houdt per mislukt bestand bij of het een bericht of een afleveringsbewijs is, en de taal van een rapport, zodat het script hetzelfde type bestand in dezelfde taal opnieuw probeert. Gebruik --language om de rapporten in een andere taal opnieuw te downloaden:

organization-data-export retry-failed --language nl

retry-failed probeert alleen losse bestanden opnieuw. Als het script de gesprekken van een maand of de berichten van een gesprek niet kan ophalen, gaat het verder met de rest en markeert het die maand niet als voltooid. De samenvatting toont hoeveel lijsten niet zijn opgehaald. Voer dezelfde export opnieuw uit met --resume om die maanden af te ronden. Een gesprek dat tijdens de export is verwijderd, telt niet als mislukte lijst: het script slaat het over, markeert de maand toch als voltooid en toont het aantal verwijderde gesprekken in de samenvatting. Als een lijst niet kan worden opgehaald door een fout die opnieuw proberen niet oplost, bijvoorbeeld voor een mailbox die tijdens de export is verwijderd, toont de samenvatting die lijst apart met de fout. --resume rondt die maanden pas af als de oorzaak van de fout is opgelost, en slaat een mailbox die niet meer bestaat over.

Outputstructuur

Geëxporteerde bestanden worden opgeslagen in de volgende structuur:

exports
└── user@example.com
    └── 202601
        └── conversation-id
            ├── 0001_20260115T093000Z.eml
            ├── 0001_20260115T093000Z.pod.pdf
            ├── 0002_20260116T101500Z.eml
            └── 0002_20260116T101500Z.pod.pdf

De .pod.pdf-bestanden worden alleen gedownload als content de waarde pod bevat.

Rapporten exporteren met het Python-script

Het script kan ook het afleveringsbewijs van elk bericht exporteren. Proof of Delivery moet zijn ingeschakeld voor je organisatie. Kies met --content wat het script per bericht downloadt en stel met --language de taal van de rapporten in:

Zonder --content exporteert het script alleen de berichten, zoals voorheen. Bestaande commando’s en configuratiebestanden blijven zonder wijzigingen werken.

Je kunt content en language ook in het configuratiebestand instellen. Het script stopt voordat het begint als de taal niet wordt ondersteund.

Het script slaat elk rapport op naast het bijbehorende bericht, met .pod.pdf in plaats van .eml. Het rapport van 0001_20260115T093000Z.eml wordt bijvoorbeeld opgeslagen als 0001_20260115T093000Z.pod.pdf. Daarnaast doet het script het volgende:

• Het slaat doorgestuurde kopieën over, omdat die geen rapport hebben, en telt ze apart in de samenvatting. Ze worden niet gelogd als mislukte downloads.
• Het stopt met een foutmelding als de API een verzoek weigert met status 403, bijvoorbeeld als Proof of Delivery of de export-API niet is ingeschakeld voor je organisatie. Voer na het inschakelen hetzelfde commando opnieuw uit met --resume om verder te gaan.
• Het verdeelt de rate limit van het API-token over de gelijktijdige downloads, en vertraagt voordat de limiet op is. Het wacht het aantal seconden in de Retry-After-header af als de API daarom vraagt.
• Het downloadt een rapport niet opnieuw als het al bestaat, ook niet als het bericht in de tussentijd is ingetrokken of verwijderd en een andere naam heeft gekregen.
• Het voegt de rapporten toe aan een bestaande export van berichten zonder de berichten opnieuw te downloaden.

Bestaande rapporten worden niet opnieuw gedownload, ook niet als je een andere --language gebruikt. Gebruik een nieuwe outputmap om ze opnieuw te downloaden, bijvoorbeeld om nieuwe gebeurtenissen op te nemen.

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
• Afleveringsbewijzen in de taal van je keuze
• 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