> For the complete documentation index, see [llms.txt](https://docs.aurinko.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.aurinko.io/brightsync/crm-connector-requirements/email-sync-api-requirements.md).

# Email Sync API Requirements

BrightSync will interact with the following endpoints on your CRM connector to log, retrieve, and update email objects.

### Email Logging Object

BrightSync requires a CRM object (e.g., an Email, Activity, Task, or Note) that can store logged email content. Your API must be capable of receiving a payload containing the following or similar fields. At least subject and body should be supported.

<table data-header-hidden><thead><tr><th width="127.1087646484375"></th><th width="116.4698486328125"></th><th></th></tr></thead><tbody><tr><td>API Field</td><td>Data Type</td><td>Description</td></tr><tr><td><code>msgId</code></td><td>String</td><td>Unique identifier assigned to the logged message by a mailbox provider, i.e. Gmail or Outlook.</td></tr><tr><td><code>syncThreadId</code></td><td>String</td><td>BrightSync generated global thread ID to group related messages.</td></tr><tr><td><code>inReplyTo</code> </td><td>String</td><td>Message ID of the email this message is a reply to.</td></tr><tr><td><code>receivedAt</code></td><td>DateTime</td><td>Timestamp when the message was received.</td></tr><tr><td><code>rfc822MsgId</code> </td><td>String</td><td>The Internet Message ID (RFC822 header) </td></tr><tr><td><code>subject</code></td><td>String</td><td>Email subject.</td></tr><tr><td><code>fromAddress</code>, <code>fromName</code></td><td>String</td><td>Sender details.</td></tr><tr><td><code>toAddresses</code>, <code>ccAddresses</code>, <code>bccAddresses</code></td><td>List</td><td>Recipient lists.</td></tr><tr><td><code>textBody</code>, <code>htmlBody</code></td><td>String</td><td>Email content.</td></tr><tr><td><code>attachments</code></td><td>List&#x3C;Attachment></td><td>List of attachment objects.</td></tr><tr><td><code>relatedTo</code></td><td>RealtedTo</td><td>The CRM object(s) (Contact, Lead, etc.) this email is logged against.</td></tr></tbody></table>

### Email Sync API Endpoints

At minimum an API endpoint for creating an Email object should be provided:\
\
**Create New Email** - Endpoint for creating a new email record. `POST/api/v1/emails`

**Load Email by ID** - Endpoint to retrieve an email using the CRM's native record ID. `GET/api/v1/emails/{id}`

**Lookup by RFC822 Msg ID** - Endpoint to look up an existing email using the `rfc822MsgId`. `GET/api/v1/emails?rfc822MsgId={value}`

**Update Existing Email** - Endpoint for updating an existing email object. While rare, this is required for specific sync scenarios, such as linking the email to a newly created contact.`PATCH` or `PUT` `/api/v1/emails/{id}`

### Contact API Endpoints

Email Sync relies on the following lookups to match emails to existing records, or to facilitate the optional auto-creation process.

**Lookup Contact by Email** - Endpoint to look up a Contact record using one or more email addresses. BrightSync will pass a list of email addresses, or call the aPI multiple times and the API should return a list of matching Contact objects. `GET/api/v1/contacts/lookup?emails={list_of_emails}`

**Load Contact by ID** - Endpoint to retrieve a single Contact record using its unique ID. `GET/api/v1/contacts/{id}`

**Lookup Company by Domain** - Endpoint to look up a Company/Account record using a domain name (e.g., `aurinko.io`). This is used for auto-creation logic.`GET` `/api/v1/companies/lookup?domain={domain_name}`

The Contact Object provided by your API in lookup and load operations must include at least the following minimal fields for BrightSync to perform matching and logging operations:

| Field Name       | Data Type     | Purpose                                                                                                      |
| ---------------- | ------------- | ------------------------------------------------------------------------------------------------------------ |
| `id`             | String        | The unique identifier for the Contact in your CRM.                                                           |
| `firstName`      | String        | Contact's first name.                                                                                        |
| `lastName`       | String        | Contact's last name.                                                                                         |
| `emailAddresses` | List\<String> | A list of all known email addresses for the contact (Primary, Secondary, etc.). Required for email matching. |
| `companyId`      | String        | The ID of the associated Company/Account record (if applicable).                                             |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.aurinko.io/brightsync/crm-connector-requirements/email-sync-api-requirements.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.