Mailbox sync

Every record bind.co serves comes from the user's mailbox. A mailbox sync is bind.co reading that mailbox: it stores the new mail, then brings the records built from it up to date. Your application does not start syncs; webhooks tell it when there is something new to read. This guide covers what your application should do with those webhooks, and what a sync never changes.

What your application should do

• Start with consent.granted and a read. When the user connects your application, read the records your scopes allow. They may already be there, or not yet.
• Do not wait for "first". .first_completed events are sent once per user, not per application: if the user already used bind.co through another application, you never receive them. They are useful as an early signal when they do arrive, never as a requirement.
• Keep data fresh with .completed events. On each one, re-read the records it is about. email_sync.completed carries had_work, which says whether the sync found new mail. The other families carry counts (created and updated, or operations_created and operations_updated) that say whether anything changed.
• Handle each event on its own. Do not rely on the order in which events of different families arrive; re-read the resource each one names.

What a sync never does

• It never overwrites a person's decision. A profile, contact or role a person saved keeps its values; when newer mail reads differently, bind.co flags a suggestion instead. A confirmed, corrected or rejected operation keeps its values.
• It never replaces a draft the user acted on. Edited, snoozed, rejected and sent drafts stay.

Duplicates

The same file always has one file_id. Contacts and operations can show up twice before bind.co recognises them as the same; when it does, it merges them afterwards. The merged record gets the status merged and leaves the lists, and a person can undo the merge with unmerge. If your application stores ids, expect a stored contact or operation to become merged.

When the user disconnects

consent.revoked tells you when the user disconnects your application; no further events are sent for them. The webhooks guide has every payload.