> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Bulk entity export by email

> Queue an asynchronous job that exports filtered entities to CSV, XLSX, or JSON and delivers the resulting file to a recipient by email.

## Overview

Exports entities using the **same filters as `GET /entities`**, builds a file (`csv`, `xlsx`, or `json`), and delivers it by email. Returns **202** with `jobId`; poll status via `GET /entities/export/jobs/{jobId}`.

## Endpoint

```
POST http://api.gu1.ai/entities/export/jobs
```

## Auth, permissions, marketplace

Same as [Email entity PDF report](/en/api-reference/entities/report-export-email): `Authorization`, `X-Organization-ID`, **`entities:export`**, **`global_sender_email`** enabled, billing **per recipient** in `recipientEmails`.

## Domain and sender

Same rules as the PDF email export:

* **`fromEmail`**: **verified** org domain; no sender row required.
* **`fromSenderId`**: UUID in `organization_email_senders`.
* Do not send both.

## Request Body

<ParamField body="recipientEmails" type="string[]" required>
  Email recipients (max **26** after deduplication). Only these addresses; the API user’s email is **not** auto-added.
</ParamField>

<ParamField body="format" type="string" required>
  `csv`, `xlsx`, or `json`.
</ParamField>

<ParamField body="filters" type="object">
  Same shape as `GET /entities` query filters. Default `{}`.
</ParamField>

<ParamField body="emailLocale" type="string">
  `en`, `es`, or `pt` for the completion email.
</ParamField>

<ParamField body="columns" type="string[]">
  Optional snake\_case export column keys; omit or `[]` for all allowed columns.
</ParamField>

<ParamField body="fromSenderId" type="string (uuid)">
  Sender UUID. Mutually exclusive with `fromEmail`.
</ParamField>

<ParamField body="fromEmail" type="string">
  From address on a verified domain. Mutually exclusive with `fromSenderId`.
</ParamField>

### Example

```json theme={null}
{
  "recipientEmails": ["analyst@example.com"],
  "format": "xlsx",
  "emailLocale": "en",
  "fromEmail": "exports@your-domain.com",
  "filters": { "type": "person" }
}
```

## 202 response

```json theme={null}
{
  "jobId": "job-uuid",
  "message": "…"
}
```

## Job follow-up

* `GET /entities/export/jobs/{jobId}` — status (`queued`, `running`, `completed`, `failed`).
* `GET /entities/export/jobs/{jobId}/download` — download metadata when available.
* Completion email may include a signed link (depends on server S3 settings).

## 400 errors

Same pre-flight codes as [report-export-email](/en/api-reference/entities/report-export-email).

## Related

* [Email entity PDF report](/en/api-reference/entities/report-export-email) — `POST /entities/{id}/report-export/email`.