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