# Export data via API

## 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](https://docs.zivver.com/en/admin/webapp/references/export-data-zivver-message.html) 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.

### /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](https://python-poetry.org/docs/#installation) is installed (recommended)
- API access is 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](https://docs.zivver.com/downloads/admin/webapp/data-export/organization-data-export.zip)

### Configuration

#### API token (required)

Set your API token as an environment variable:

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

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

```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
}
```

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.

```bash
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

### Installation

#### Using Poetry (recommended)

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

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

```bash
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:

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

#### Export specific email addresses

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

```bash
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:

```bash
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:

```bash
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:

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

### Output structure

Exported files are stored in the following structure:

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

### Important considerations

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

**How to enable the API endpoints?** The API endpoints are disabled by default. Create a support ticket to have them enabled for your organization.

**What to do if the script stops midway?** Run the same command again and use the `--resume` flag to continue where it left off.

**Some files failed to download. How to retry?** Use the following command to retry only the failed downloads:

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

**How to export data for specific users only?** Use `allowed_emails` to include specific users, or `allowed_domains` to include entire domains. You can also use `exclude_emails` to skip specific addresses.

**When to use the API method instead of the ZIP export?** Use the API method for large organizations, partial exports, or when the ZIP export is not suitable.