> ## 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.

# Email entity PDF report

> Queue a server-generated entity PDF report (same layout as the dashboard export) and email it to one or more recipients via the entities API.

## Overview

Queues **asynchronous** generation of a full entity PDF on the server and delivery by email. The PDF uses the same **jsPDF** pipeline as the in-app “export report” download. Your integration calls this endpoint with an API key; recipients receive the attachment (subject/body depend on `emailLocale`).

<Note>
  The HTTP response is **202 Accepted** as soon as the job is queued. Generation and sending happen in the background; failures are logged server-side (check support if emails do not arrive).
</Note>

## Endpoint

```
POST http://api.gu1.ai/entities/{id}/report-export/email
```

## Authentication & tenant

<ParamField header="Authorization" type="string" required>
  `Bearer YOUR_API_KEY` — see [Authentication](/en/api-reference/authentication).
</ParamField>

<ParamField header="X-Organization-ID" type="string" required>
  Production or Sandbox organization UUID — see [Environments](/en/api-reference/environments).
</ParamField>

## Permissions

Requires granular permission **`entities:export`** on the API key (same as `POST /entities/{id}/export` and `GET /entities/{id}/export-data`).

## Marketplace and billing

* The organization must have **`global_sender_email`** enabled (Applications / Marketplace) and the API must have **MS Provider** configured.
* Each address in `recipientEmails` (after server-side deduplication) bills **one Email pack execution** or, if no pack remains, **tokens** per `base_price_cents`.
* Pre-flight checks balance/executions for **all** recipients before queuing.

## Domain and sender (`fromEmail`)

To send from your organization:

1. Register the domain under **Settings → Email → Domains** and complete DNS verification.
2. Send **`fromEmail`** in the body with any address on that domain (e.g. `noreply@your-domain.com`). You **do not** need a matching row under **Senders** when the domain is already verified.
3. Alternatively, send **`fromSenderId`** (UUID from `organization_email_senders`).
4. Omit both for the platform default (`noreply@gueno.com`).

Do not send `fromSenderId` and `fromEmail` in the same request.

## Path parameters

<ParamField path="id" type="string" required>
  Entity UUID (`id` returned by create/list/get).
</ParamField>

## Request body (JSON)

<ParamField body="recipientEmails" type="string[]" required>
  One or more email addresses (max **26** after deduplication). Email is sent **only** to these addresses; the API key user’s account email is **not** added automatically.
</ParamField>

<ParamField body="emailLocale" type="string">
  Email template language: `en`, `es`, or `pt`. Defaults to `en` if omitted or invalid.
</ParamField>

<ParamField body="fromSenderId" type="string (uuid)">
  UUID of a sender under **Settings → Email → Senders**. Mutually exclusive with `fromEmail`.
</ParamField>

<ParamField body="fromEmail" type="string">
  Full From address (e.g. `reports@your-domain.com`). The domain must be **verified** for the org. If a sender row exists for that address, its display name is used; otherwise a verified domain is enough. Mutually exclusive with `fromSenderId`.
</ParamField>

<ParamField body="sections" type="object" required>
  Booleans for each report section (same semantics as the dashboard export modal). All keys optional; defaults match the API validator (`generalInfo` defaults to `true`, others to `false` if omitted).

  Keys: `generalInfo`, `kyc`, `documents`, `checks`, `enrichments`, `alerts`, `aiAnalysis`, `relationships`, `timeline`, `riskAnalysis`.
</ParamField>

### Example body

```json theme={null}
{
  "recipientEmails": ["compliance@example.com"],
  "emailLocale": "en",
  "fromEmail": "noreply@your-domain.com",
  "sections": {
    "generalInfo": true,
    "riskAnalysis": true,
    "enrichments": true,
    "alerts": true
  }
}
```

## Example request

```bash theme={null}
curl -X POST "http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000/report-export/email" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Organization-ID: YOUR_ORG_UUID" \
  -H "Content-Type: application/json" \
  -d '{
    "recipientEmails": ["compliance@example.com"],
    "emailLocale": "en",
    "fromEmail": "noreply@your-domain.com",
    "sections": {
      "generalInfo": true,
      "riskAnalysis": true,
      "enrichments": true
    }
  }'
```

## Responses

### 202 Accepted — queued

```json theme={null}
{
  "success": true,
  "status": "queued",
  "message": "…"
}
```

`message` is localized from `emailLocale`.

### 400 — validation / pre-flight

| Code / case                  | Description                                                   |
| ---------------------------- | ------------------------------------------------------------- |
| `NO_RECIPIENTS`              | Empty `recipientEmails` after deduplication.                  |
| `TOO_MANY_RECIPIENTS`        | More than 26 recipients.                                      |
| `EMAIL_INTEGRATION_INACTIVE` | `global_sender_email` disabled or MS Provider not configured. |
| `DOMAIN_NOT_VERIFIED`        | `fromEmail` domain not registered or DNS not verified.        |
| `SENDER_NOT_CONFIGURED`      | Unknown `fromSenderId` for the org.                           |
| `INVALID_SENDER`             | Both `fromSenderId` and `fromEmail`, or invalid format.       |
| `INSUFFICIENT_BALANCE`       | Not enough tokens or pack executions for all recipients.      |

### 404 — entity not found or hidden

Same shape as other entity routes when the ID does not exist in the org or [entity visibility](/en/monitoring/overview) denies the caller.

### 500 — server error

Rare; includes a generic error payload.

## Related endpoints

* **`POST /entities/{id}/export`** — synchronous PDF download (response body = PDF file).
* **`GET /entities/{id}/export-data`** — JSON bundle used by the dashboard export; the email PDF uses the same server-side data assembly.
* [**Bulk export by email**](/en/api-reference/entities/export-jobs-email) — `POST /entities/export/jobs` (CSV/XLSX/JSON with list filters).
* [Get entity](/en/api-reference/entities/get) — `GET /entities/{id}`.