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

# Overview

> Read the email linked to a record, send email from it, and decide which email links to it

A record's email is the email linked to a claim, an insured, a submission, a
quote, a policy, a person or an organization. These endpoints read it, send
email from the record, and change what links to it. They do what the record's
**Emails** tab and **Send email** do in the app.

A policy's email lives under the policy API, like the rest of a policy. Every
path below also exists as `/policies/{policyId}/…`, for example
`/policies/{policyId}/email-conversations`. Reading needs `policy.view`, and
linking earlier email needs `policy.endorse`. As with every `/entities`
endpoint, `/entities/policy/…` answers `400`.

Email is being turned on company by company. While it is off for your
company, every endpoint here answers `404`.

## How email links to a record

Email links to a record through the people on it. For a claim, those are its
contacts and the plaintiffs' and defendants' attorneys. Email from or to one
of them links to the claim from the day they were added to it. Email sent
from the platform on the record, and email that created the record through
the intake inbox, link to it too.

A person or organization shows its last 12 months of email unless you pass
`from` or `to`.

## Reading

| Method | Path | Does |
| - | - | - |
| `GET` | `/entities/{entityType}/{entityId}/email-conversations` | Lists the conversations, newest activity first, 50 per page |
| `GET` | `/entities/{entityType}/{entityId}/email-conversations/{threadId}` | Reads one conversation, every message |
| `GET` | `/entities/{entityType}/{entityId}/email-link-events` | Lists what was linked or removed, when, why and by whom |

A key or user without `email.view` sees only email sent from the platform.

**Records a conversation names.** Each conversation lists in `mentions` the
other records its messages name by number: a claim number, quote number,
submission number or policy number, with or without the policy's year. A
number that no record carries is left out. `mentionsRecord` says a message
names this record's own number. An exposure, person or organization has no
number, so for them `mentionsRecord` says the conversation names any record,
and the `mentionsRecord=true` filter keeps those conversations.

## Changing what links

| Method | Path | Does |
| - | - | - |
| `POST` | `/entities/{entityType}/{entityId}/email-people/{personId}/link-earlier` | Links a person's email from an earlier date |
| `POST` | `/entities/{entityType}/{entityId}/email-people/{personId}/unlink` | Removes the email that came through a person, from a date |
| `POST` | `/entities/{entityType}/{entityId}/email-conversations/{threadId}/remove` | Removes a conversation from the record |

**After adding a person.** Their email links from the day they were added.
To bring in their earlier email, call
[Link Earlier Record Emails](https://docs.go.aiinsurance.io/api-reference/record-emails/link-earlier-record-emails.md)
with the date to link from, such as the claim's created date. Its linking
runs in the background.

**After removing a person.** Their email stays on the record. To remove it,
call [Unlink Record Person Emails](https://docs.go.aiinsurance.io/api-reference/record-emails/unlink-record-person-emails.md)
with the date to remove from. Email that another person on the record is also
on stays.

A link someone removed stays removed. Linking a person's earlier email does
not bring it back. Removing needs `email.unlink`.

## Sending

A claim, insured, quote, policy or submission sends email from a template of
its record type. A quote or policy can also send from one of its packets: the email's
Packet URL smart tag links to the packet, and it can attach the packet's PDF.

| Method | Path | Does |
| - | - | - |
| `GET` | `/entities/{entityType}/{entityId}/sendable-email-templates` | Lists the templates the record can send; `fromPacket=true` adds those that need a packet |
| `POST` | `/entities/{entityType}/{entityId}/emails/preview` | Renders a template against the record, without sending |
| `POST` | `/entities/{entityType}/{entityId}/emails` | Sends a template from the record or one of its packets |
| `POST` | `/entities/{entityType}/{entityId}/email-deliveries/{deliveryId}/retry` | Queues a failed send again |
| `GET` | `/entities/{entityType}/{entityId}/packet-emails` | Lists the emails sent from the record's packets |

Sending needs `email.send` and view on the record. Listing packet emails needs
only view.

**Recipients.** Send uses only the `to` and `cc` you pass. Preview first and
pass its `to` and `cc` to send what the template resolves to.

**Following a send.** Send stores the email on the record and answers with
its `deliveryId` and `threadId` before the email goes out. On
[Get Record Email Conversation](https://docs.go.aiinsurance.io/api-reference/record-emails/get-record-email-conversation.md)
the message's `delivery.status` moves from `queued` to `sent`, or to `failed`
with a `reason`. A failed send can be retried; the same stored email is sent
again.

**Sending once.** Send a new `Idempotency-Key` header for each email.
Retrying the request with the same key returns the first send and sends
nothing new.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.