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

# Emails

> Individual email records, sends, replies, and interested replies, linked to a contact.

An Email is a single email record: an outbound send, an inbound reply, or a bounce, linked to a contact. Emails carry their own custom fields, separate from contact and company custom fields, and can be marked "interested" to flag a positive reply.

## Configuration

|                       |                                                                                                  |
| --------------------- | ------------------------------------------------------------------------------------------------ |
| API path              | `/public/emails`                                                                                 |
| Get / delete a record | `/public/emails/{email_id}`                                                                      |
| Mark interested       | `/public/emails/set-interested`                                                                  |
| Custom fields         | `/public/emails/{email_id}/custom-fields`                                                        |
| MCP filter entity     | `email` (via `query_entity`), also reachable as the `emails` relation on `contact` and `company` |

## Attributes

| Attribute     | API field         | Type     | Writable?                           | Notes                                                                                              |
| ------------- | ----------------- | -------- | ----------------------------------- | -------------------------------------------------------------------------------------------------- |
| ID            | `id`              | integer  | No                                  | Set by RevyOps                                                                                     |
| Updated Date  | `updated_time`    | datetime | No                                  |                                                                                                    |
| Timestamp     | `email_timestamp` | datetime | Yes                                 | When the email was sent or received                                                                |
| Contact Email | `contact_email`   | string   | Yes                                 | Email address of the contact side of the thread                                                    |
| Contact ID    | `contact_id`      | integer  | Yes                                 | Alternative to `contact_email` for linking the record to a contact                                 |
| Agent Email   | `agent_email`     | string   | Yes                                 | The sending mailbox, for outbound emails                                                           |
| Email Type    | `email_type`      | string   | **Required.**                       | `INBOUND`, `OUTBOUND`, or `BOUNCED`                                                                |
| Subject       | `subject`         | string   | Yes                                 |                                                                                                    |
| Body (text)   | `body_text`       | string   | Yes                                 |                                                                                                    |
| Body (HTML)   | `body_html`       | string   | Yes                                 |                                                                                                    |
| Campaign ID   | `campaign_id`     | string   | Yes                                 |                                                                                                    |
| Campaign Name | `campaign_name`   | string   | Yes                                 |                                                                                                    |
| Interested    | `interested`      | boolean  | Yes                                 | Set directly on create/update, or through `POST /public/emails/set-interested`                     |
| Origin        | `origin`          | string   | **Required.**                       | The platform or source the email came from, e.g. `instantly`, `smartlead`, `emailbison`, `lemlist` |
| Custom Fields | `custom_fields`   | array    | Yes, via the custom fields endpoint | See below                                                                                          |

### Sends and replies

`email_type` distinguishes the three kinds of email record: `OUTBOUND` for a send, `INBOUND` for a reply, `BOUNCED` for a bounce. `POST /public/emails` creates any of the three; `GET /public/emails` searches across all of them, filterable by `campaign_id`, `contact_email`, `origin`, and `subject`.

### Interested

`POST /public/emails/set-interested` sets `interested` to `true` on the email matching the given `email`, `subject`, and optional `disposition`. This is the same flag surfaced as `interested` on the Email object and used to filter campaign reporting.

| Attribute   | API field     | Type   | Writable?     | Notes                          |
| ----------- | ------------- | ------ | ------------- | ------------------------------ |
| Email       | `email`       | string | **Required.** | Contact email address to match |
| Subject     | `subject`     | string | **Required.** | Email subject to match         |
| Disposition | `disposition` | string | Optional      |                                |

### Custom fields on emails

Email custom fields are separate from contact and company custom fields: they're defined per field name directly on the email record, not through the [custom fields schema](/data-model/custom-fields) endpoint.

`POST /public/emails/{email_id}/custom-fields`

| Attribute    | API field      | Type     | Writable?     | Notes                |
| ------------ | -------------- | -------- | ------------- | -------------------- |
| ID           | `id`           | integer  | No            |                      |
| Updated Date | `updated_time` | datetime | No            |                      |
| Field Name   | `field_name`   | string   | **Required.** |                      |
| Field Value  | `field_value`  | string   | **Required.** | Max 2,500 characters |

`DELETE /public/emails/{email_id}/custom-fields/{field_id}` removes one.

## Relationships

* **Contact**: every email links to one contact, by `contact_id` or by matching `contact_email`. On the contact and company entities, emails are reachable through the `emails` relation.
* **Campaign**: emails carry `campaign_id` and `campaign_name` for attribution to a sending campaign; see campaign reporting in the MCP `get_campaigns` and `get_campaign_drilldown` tools.

## Related endpoints and MCP tools

**Public API**

* `GET`/`POST /public/emails`
* `GET`/`DELETE /public/emails/{email_id}`
* `POST /public/emails/set-interested`
* `POST /public/emails/{email_id}/custom-fields`
* `DELETE /public/emails/{email_id}/custom-fields/{field_id}`

**MCP tools**

* `search_emails`, `mark_email_interested`, `get_email_thread`
* `get_filter_schema`, `query_entity` (entity `email`)
* `get_campaigns`, `get_campaign_drilldown`, `get_campaign_stats`