> 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

This document outlines the required API endpoints and data structures for integrating your CRM with BrightSync's Email Synchronization features.

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).                                             |