> For the complete documentation index, see [llms.txt](https://docs.tiny.plus/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tiny.plus/api/endpoints/emails.md).

# Emails

Emails live at `/v2/emails`. They support every request on the [Records](/api/endpoints/records.md) page: list, get, history, create, update, delete and search. An email record is a copy of an email, logged against the records it's about.

## Logging an email

```bash
curl -X POST "https://api.tiny.plus/v2/emails" \
  -H "Authorization: Bearer {{user_access_token}}" \
  -H "Content-Type: application/json" \
  -d '{
        "subject": "Revised fee proposal",
        "body_text_raw": "Hi Adam, please find the revised proposal attached...",
        "body_html": "<p>Hi Adam, please find the revised proposal attached...</p>",
        "sender_name": "Alex Example",
        "sender_email": "alex@example.com",
        "recipients_raw": "adam@adamson.com",
        "cc_raw": "sam@example.com",
        "email_id": "AAMkAGI2TG93AAA=",
        "primary_related": "1241",
        "related_selector": ["1343", "1231"]
      }'
```

```javascript
{
    "id": "161086"
}
```

* `subject` becomes the email's `name`.
* `body_text_raw` is the plain-text body. The email's `description` is set to its newest part: the reply, without the quoted thread below it.
* `recipients_raw` and `cc_raw` are email addresses separated by commas. They're stored as sent, and not matched to contacts.
* `primary_related` is the record the email is mainly about, such as a contact. The people following that record are notified.
* `related_selector` links the email to more records, and to team members. See [Linking records](/api/concepts/linking.md#linking-other-records).
* `assigned_user` is the token's user unless you send another.

## Avoiding duplicates

`email_id` is your own unique id for the email, such as the id your mail system gives it. If an email with the same `email_id` has already been logged, a second one fails with `400`:

```javascript
{
    "error": "A processing error occurred while adding this record. - 24"
}
```

To check first, filter on it:

```bash
curl "https://api.tiny.plus/v2/emails?email_id=AAMkAGI2TG93AAA%3D&fields=id&return_format=array&with_related=0" \
  -H "Authorization: Bearer {{user_access_token}}"
```

tiny+ only checks for duplicates when the `email_id` is longer than five characters.

## Fields

| Field             | Label in tiny+  | Type          | Notes                                                                                                                                  | Editable |
| ----------------- | --------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `body_html`       | Email           | Text          | The HTML body.                                                                                                                         | Yes      |
| `body_text_raw`   | Body Text       | Text          | The plain-text body. The email's `description` is set to its newest part.                                                              | Yes      |
| `cc_raw`          | CCed            | Text          | CC'd email addresses, separated by commas.                                                                                             | Yes      |
| `conversation_id` | Conversation ID | Text          | Your id for the email's thread. Stored as sent.                                                                                        | Yes      |
| `email_id`        | Email ID        | Text          | Your unique id for the email. A second email with the same one is refused: see [Avoiding duplicates](#avoiding-duplicates).            | Yes      |
| `mail_to`         | To              | Text          | The To line, as text.                                                                                                                  | Yes      |
| `recipients_raw`  | Recipients      | Text          | Recipients' email addresses, separated by commas.                                                                                      | Yes      |
| `sender_email`    | Sender Email    | Email address | The sender's email address.                                                                                                            | Yes      |
| `sender_name`     | From            | Text          | The sender's name.                                                                                                                     | Yes      |
| `sender_raw`      | From            | Text          | The sender as one string, such as `Alex Example <alex@example.com>`. Used for `sender_name` and `sender_email` when those aren't sent. | Yes      |
| `subject`         | Subject         | Text          | The email's subject. It becomes the email's `name`.                                                                                    | Yes      |