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

# POST /sharePresentationViaEmail

> Email an existing shared presentation to one or more recipients with per-recipient tracked links

<Note>
  For most use cases, the [`slideless` CLI](/cli/overview) is easier than calling this endpoint directly. The CLI command equivalent is `slideless share-email <presentationId> --to <email>`. End-to-end walkthrough: [Send a presentation by email](/guides/sharing-via-email).
</Note>

## When to use

You already have a `presentationId` (from [`POST /commitPresentationVersion`](/api-reference/commit-presentation-version) or `slideless share`) and you want to email it to one or more recipients. The endpoint:

* Mints a **unique named token per recipient** by default (recipient email becomes the token name), so per-recipient open tracking comes for free via the existing `accessCount` / `lastAccessedAt` fields on each `ShareToken`.
* Sends a branded email via Resend (from `noreply@mail.slideless.ai`).
* Records every send in `shared_presentations/{presentationId}/email_sends/{autoId}` as an append-only audit trail.

To reuse a single token for every recipient (shared view count, one revoke kills all), pass `tokenId`.

## Endpoint

```
POST https://europe-west1-slideless-ai.cloudfunctions.net/sharePresentationViaEmail
```

## Auth

| Header          | Value                                                  |
| --------------- | ------------------------------------------------------ |
| `Authorization` | `Bearer cko_…` (org key) or `Bearer cka_…` (admin key) |
| `Content-Type`  | `application/json`                                     |

Required scope: `presentations:write`. Organization keys must belong to the same org as the `presentationId`.

## Request body

| Field            | Type      | Required | Description                                                                                                                                        |
| ---------------- | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `presentationId` | string    | yes      | The presentation to email. Must belong to the caller's org.                                                                                        |
| `emails`         | string\[] | yes      | 1–20 recipient email addresses. Case-insensitive, de-duplicated.                                                                                   |
| `message`        | string    | no       | Personal note shown in the email body. ≤2000 chars.                                                                                                |
| `subject`        | string    | no       | Custom subject line. Defaults to `"<senderEmail> shared: <title>"` (or `"Shared with you: <title>"` if no sender email is known). ≤200 chars.      |
| `tokenId`        | string    | no       | If set, reuse this existing token for every recipient instead of minting per-recipient tokens. Must be an active (non-revoked) token on the share. |

Example:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "presentationId": "0192f1c3-8b1a-7c4d-9e3f-...",
  "emails": ["alice@example.com", "bob@example.com"],
  "message": "Here's the Q2 deck we discussed."
}
```

## Response (200)

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "success": true,
  "data": {
    "presentationId": "0192f1c3-...",
    "sent": [
      {
        "email": "alice@example.com",
        "tokenId": "0192f1c3-...",
        "resendMessageId": "re_abc123",
        "shareUrl": "https://app.slideless.ai/share/0192f1c3-...?token=..."
      }
    ],
    "failed": [
      { "email": "bob@bad", "code": "invalid-email", "message": "Not a valid email address." }
    ],
    "summary": { "total": 2, "sent": 1, "failed": 1 }
  }
}
```

`data.failed[]` contains **per-recipient** failures inside an otherwise-200 response. The endpoint only returns a non-2xx status when a preflight condition fails (auth, not-found, too-many-recipients, …) — i.e. when no email could be attempted for any recipient.

## Error responses

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "success": false,
  "error": {
    "code": "permission-denied",
    "message": "API key does not have access to this share.",
    "nextAction": "Confirm the share belongs to the same org as the current API key. If not, ask the user for the correct key."
  }
}
```

| Status | `code`                | When                                                          |
| ------ | --------------------- | ------------------------------------------------------------- |
| 400    | `missing-recipients`  | `emails` was empty                                            |
| 400    | `too-many-recipients` | >20 recipients                                                |
| 400    | `message-too-long`    | `message` >2000 chars                                         |
| 400    | `invalid-argument`    | Invalid `presentationId`, subject too long, unknown `tokenId` |
| 401    | `unauthenticated`     | Missing/invalid API key                                       |
| 403    | `permission-denied`   | Key doesn't belong to the share's org                         |
| 404    | `not-found`           | `presentationId` doesn't exist                                |
| 429    | `rate-limited`        | Too many calls                                                |
| 500    | `internal`            | Backend error                                                 |

Every error response includes a `nextAction` string written for consumers (including agents) to act on programmatically.

## Examples

### curl

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS -X POST \
  -H "Authorization: Bearer $SLIDELESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "presentationId": "0192f1c3-8b1a-7c4d-9e3f-...",
    "emails": ["alice@example.com", "bob@example.com"],
    "message": "Here is the Q2 deck."
  }' \
  https://europe-west1-slideless-ai.cloudfunctions.net/sharePresentationViaEmail
```

### Node.js

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
const res = await fetch(
  'https://europe-west1-slideless-ai.cloudfunctions.net/sharePresentationViaEmail',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.SLIDELESS_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      presentationId: '0192f1c3-...',
      emails: ['alice@example.com'],
      message: 'Here is the Q2 deck.',
    }),
  },
);
const body = await res.json();
if (!body.success) {
  throw new Error(`${body.error.code}: ${body.error.message} — ${body.error.nextAction}`);
}
console.log(`Sent to ${body.data.summary.sent} of ${body.data.summary.total}`);
```

## See also

* [Send a presentation by email (guide)](/guides/sharing-via-email)
* [`POST /commitPresentationVersion`](/api-reference/commit-presentation-version) — to create the `presentationId` in the first place
* [Share tokens](/concepts/share-tokens) — the per-recipient token model