Introduction

Export all Zivver messages that were sent and received by your organization for archiving purposes. This method allows you to export messages via the Zivver API.

This export method is recommended for:

• Organizations with a large number of messages
• Exporting data for a subset of users
• Situations where the ZIP export is not suitable

For smaller organizations with a limited number of messages, we recommend using the Zivver WebApp method to export all messages in a ZIP file via a Zivver message.

API overview

The sections below provide an overview of the API endpoints used for exporting data. After the API is enabled for your organization, you can use these endpoints to manage your exports via a script or an API client (e.g. Postman). All endpoints require authentication via an API token, which you generate in the Zivver admin portal.

The base URL for all endpoints is https://app.zivver.com/api, and all requests use the GET method.

Note

The API endpoints are disabled by default. Create a support ticket to enable them for your organization.

/exports/mailbox

With this endpoint, you can retrieve a list of all mailboxes in your organization. This endpoint is the starting point for the export process, as you need to know which mailboxes to export.

Include the following headers in your request:

• Authorization: Bearer {API_TOKEN}
• Accept: application/json

/exports/mailbox/{email_address}

Use this endpoint to retrieve a list of months for which there are conversations in a specific mailbox. This allows you to identify which months have data available for export.

Include the following headers in your request:

• Authorization: Bearer {API_TOKEN}
• Accept: application/json

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

This endpoint retrieves a list of conversations in a specific month for a specific mailbox. This helps you identify which conversations you want to export.

Include the following headers in your request:

• Authorization: Bearer {API_TOKEN}
• Accept: application/json

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

Use this endpoint to retrieve a list of messages in a conversation for a specific month and mailbox. This allows you to see the individual messages that are part of the conversation.

Include the following headers in your request:

• Authorization: Bearer {API_TOKEN}
• Accept: application/json

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

This endpoint allows you to download a specific message in a conversation for a specific month and mailbox. The message is downloaded in EML format, which can be opened with email clients or imported into other systems.

Include the following headers in your request:

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

Python export script

To simplify the export process, we provide a Python script that automates the API calls and handles the export logic. The script supports features such as filtering by email address or domain, resuming interrupted exports, and retrying failed downloads. The script is included in the export package that you can download from the link below. It is designed to be run from the command line and can be configured using a configuration file or command line arguments.

Requirements

Before you begin, make sure you meet the following requirements:

• Python 3.9 or higher is installed
• Poetry is installed (recommended)
• API access is enabled for your organization

Note

The API endpoints are disabled by default. Create a support ticket to have them enabled for your organization.

Download

Download the export package, which includes the Python script, a README file, and a sample configuration file:

Download export script

Configuration

API token (required)

Set your API token as an environment variable:

export ZIVVER_API_TOKEN="your-token-here"

Note

For security reasons, we recommend the API token to be set using the ZIVVER_API_TOKEN environment variable and should not be stored in the configuration file.

Option 1: Configuration file

Use a configuration file if you want to manage all settings in one place.

Create a config.json file (see the example included in the 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
}

This approach is recommended when:

• You want a reusable configuration
• You are running multiple exports with the same settings

Option 2: Command line arguments

Use command line arguments if you prefer to quickly run one-off exports without creating a config file.

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

This approach is useful when:

• You want to override specific settings
• You are testing or running ad-hoc exports

Note

When using both allowed_emails and allowed_domains, emails matching either condition are included (OR logic).

Installation

Using Poetry (recommended)

Use this method if you want to run the script in a managed Python environment with all dependencies handled automatically.

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

This will:

• Install all required dependencies
• Allow you to run the script using poetry run

Using a built package (wheel)

Use this method if you prefer a standard installation that makes the command globally available.

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

This will:

• Build the package
• Install it so you can run organization-data-export directly

Usage

Full export

Use this command to export all available data using a configuration file:

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

Export specific email addresses

Use this when you only want to export data for selected users:

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

Export specific domains

Use this when you want to export all users within one or more domains:

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

Resume an interrupted export

If an export was interrupted (for example due to a network issue or manual stop), you can resume it:

organization-data-export export --resume

This will continue from where the previous run stopped without re-downloading existing data.

Retry failed downloads

If some files failed to download, you can retry only those files:

organization-data-export retry-failed

Output structure

Exported files are stored in the following structure:

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

Important considerations

Warning

Large mailboxes can take hours to export. Long export times are expected.

• Progress is not linear: some mailboxes complete quickly, others take much longer
• The script processes one month at a time per mailbox
• The export may appear to be stuck, but is still running
• Rate limiting is handled automatically

Features

• Resumable exports using --resume
• Flexible filtering by email address and domain
• Concurrent downloads (configurable)
• Automatic retry for failed downloads
• Logging of failed downloads
• Secure authentication via environment variables

Limitations

• API access must be enabled by Zivver for security purposes
• If you want to use Zivver’s export script, Python installation is required
• The API token must be set again for each session (unless configured permanently)

FAQ

organization-data-export retry-failed