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.

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

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