Overview
FranConnect can display and attach email from your own mailbox through the Email Integration service, so that correspondence can be filed against CRM records. This article explains exactly how that connection is established, what FranConnect stores, what it can and cannot do inside your mailbox, and how you can restrict or revoke access at any time.
It is written for administrators, IT teams, and security reviewers who need a precise answer to the question: “What can FranConnect access in our email account?”
1. Summary at a Glance
| Question | Answer |
| Authentication model | Provider OAuth 2.0 Authorization Code Grant, consented interactively by the individual user at Microsoft or Google. No stored mailbox passwords, no IMAP/SMTP/POP, no service-account impersonation. |
| Credentials stored | Per-user access and refresh token, the connected email address and display name, and the user’s folder selections — keyed by tenant and user. FranConnect’s own app registration (client ID and secret) is platform-level, not customer data. |
| Scopes granted | Read-only. Microsoft: mail.read, user.read, offline_access. Google: gmail.readonly, gmail.labels. That is the complete list — see Section 4. |
| Operations available | Identify the connected account; list folders; list, search, and read messages in the user-selected folders; download attachments; copy user-selected messages into FranConnect records. |
| Boundaries | Cannot send email, cannot modify or delete anything in the mailbox, cannot change mailbox rules or settings, cannot reach calendars, contacts, files, or other users’ mailboxes. |
| Mailbox monitoring | None. No background sync, no scheduled jobs, no webhooks or change-notification subscriptions. The mailbox is read only while the user is actively using the feature. |
| Customer email data kept | Only the messages a user opens or uploads through FranConnect (subject, addresses, dates, body, attachments). The rest of the mailbox is never copied — see Section 7. |
| Tenant isolation | Uploaded email records live in your tenant’s own database; all service-side data is keyed by tenant and user, derived from the authenticated request. |
| Customer control | The user or their administrator can revoke FranConnect’s access unilaterally at Microsoft or Google at any time; the integration can also be disconnected per user inside FranConnect. |
2. Authentication Model
FranConnect uses the standard OAuth 2.0 Authorization Code Grant (three-legged, user-consented) with the Microsoft Identity Platform (Azure AD) and with Google. It does not use application or daemon permissions, domain-wide delegation, service-account impersonation, or any password-based mail protocol such as IMAP, SMTP, POP, or EWS.
How the connection is established
- Open the configuration screen. A FranConnect user opens the email configuration screen and chooses their provider — Gmail, Outlook, or Office 365. FranConnect redirects them to the provider’s own authorization endpoint, requesting response_type=code and the read-only scopes listed in Section 4.
- Authenticate and consent at the provider. The user signs in at Microsoft or Google and grants consent there. FranConnect never sees or stores their mailbox password.
- Exchange the authorization code. The provider returns an authorization code. FranConnect exchanges it server-to-server for an access token and a refresh token, authenticating as its registered application.
- Call the API with the token. All subsequent provider API calls carry the OAuth access token as a bearer token over HTTPS.
- Refresh before expiry. Access tokens are short-lived — typically about one hour, per provider policy. FranConnect treats a token as stale at roughly 75% of its lifetime and refreshes it using the refresh token; each refresh replaces the stored tokens.
Note: Consent is granted per FranConnect user — each user connects their own mailbox with their own provider identity. There is no account-wide, organization-wide, or domain-wide grant.
3. Credentials and Identifiers Stored
3.1 Per user (your data)
The following is held for each connected user, keyed by tenant and user:
| Field | Purpose |
| Tenant + FranConnect user | Identifies which tenant and user the authorization belongs to |
| Access token | Bearer token for provider API calls (short-lived) |
| Refresh token | Used to obtain a new access token without re-prompting the user |
| Token timestamps / expiry | Freshness tracking for the refresh at roughly 75% of token lifetime |
| Connected email address and display name | Returned by the provider after consent and shown in the FranConnect UI so an administrator can see which identity is connected. Identifier only — never used as a credential. |
| Selected folders | The mail folders (Inbox, Sent Items) the user chose to expose to FranConnect |
3.2 Platform-level (FranConnect’s own, not customer credentials)
FranConnect maintains its own application registrations — one multi-tenant Azure AD application and one Google Cloud OAuth client, each with a client ID and secret. These represent the identity of the FranConnect application itself, equivalent to any ISV’s client credentials. Also platform-level: the fixed Microsoft Graph and Gmail API endpoint URLs.
3.3 Explicitly not stored
- Mailbox passwords of any kind — no Microsoft or Google account password, and no app password
- IMAP, SMTP, or POP credentials — no such protocol is used anywhere in the service
- Any provider administrator credential or admin-consented application permission
4. Provider Permissions and OAuth Scopes
4.1 Microsoft (Outlook.com / Office 365), via Microsoft Graph
| Scope | Grants |
| https://graph.microsoft.com/mail.read | Read the signed-in user’s mail. Read-only. |
| https://graph.microsoft.com/user.read | Read the signed-in user’s basic profile (name, email address) |
| offline_access | Issue a refresh token so the user is not re-prompted |
Not requested, and therefore not granted: Mail.Send, Mail.ReadWrite, MailboxSettings.*, Calendars.*, Contacts.*, Files.*, Directory.*, and any .All or application (daemon) permission.
4.2 Google (Gmail)
| Scope | Grants |
| https://www.googleapis.com/auth/gmail.readonly | Read the signed-in user’s mail. Read-only. |
| https://www.googleapis.com/auth/gmail.labels | Read the user’s labels (folder list) |
Not requested, and therefore not granted: gmail.send, gmail.modify, gmail.compose, gmail.settings.*, the full https://mail.google.com/ scope, Contacts, Drive, or any other Google API.
Two consequences are worth stating explicitly:
- Every token acts strictly as the single user who consented — it confers no administrative rights and no access to any other mailbox.
- All granted mail scopes are read-only. Even with a valid token, the service is technically unable to send, alter, move, or delete anything in your mailbox.
5. Operations FranConnect Can Perform
After authentication, FranConnect performs only the following read operations:
| Operation | Provider API |
| Identify the connected account | Graph /me · Gmail users/me/profile |
| List mail folders / labels | Graph /me/mailFolders · Gmail users/me/labels |
| List and search messages in the user-selected folders (Inbox, Sent Items) | Graph /me/messages · Gmail users/me/messages |
| Read a single message (headers and body) | Graph /me/messages/{id} · Gmail users/me/messages/{id} |
| Download an attachment of a message | Graph /messages/{id}/attachments/{id} · Gmail attachment API |
That is the full list. All access is pull-based and user-initiated: a provider API call happens only when the user is actively browsing, searching, opening, or uploading email inside FranConnect.
Important: There are no scheduled jobs, no continuous sync, and no webhook or change-notification subscriptions against your mailbox. FranConnect does not monitor the mailbox in the background.
5.1 Uploading an email to a FranConnect record
When a user explicitly selects a message and uploads it against a CRM record — a lead, franchisee, owner, unit, or contact — FranConnect copies that message out of the mailbox into your own FranConnect environment:
- The message body is stored as an HTML document, and its attachments as files, in FranConnect document storage (Amazon S3).
- Message metadata — sender, recipients, subject, sent and received dates, folder, uploading user, and a pointer to the stored document — is written to your tenant’s own database, linked to the selected record.
- An upload log entry (subject, message ID, provider, status, associated records) is kept for auditability.
6. Access Boundaries — What FranConnect Cannot Do
| FranConnect cannot… | Basis |
| Send email from your mailbox | No send scope is requested — mail.read / gmail.readonly only |
| Modify, move, or delete mailbox content | All granted mail scopes are read-only |
| Change mailbox settings, rules, signatures, or forwarding | No settings scope is requested; no such API calls are made |
| Read folders other than those the user selected | The application reads only the user-configured folders (Inbox, Sent Items) |
| Access calendars, contacts, or files | No such scopes are requested |
| Access any other user’s mailbox | Delegated user consent only — no admin consent, no application permissions, no impersonation |
| Monitor the mailbox in the background | No webhooks, no change-notification subscriptions, and no scheduled sync jobs exist in the service |
| Exceed the consenting user’s own rights | Tokens operate strictly in the consenting user’s context |
7. Customer Email Data Kept by FranConnect
- Browsing is transient. Message lists and searches are fetched live from Microsoft or Google and rendered to the user. The mailbox is not bulk-copied or mirrored.
- Opened and uploaded messages are retained. Messages a user opens or uploads through FranConnect are retained by the service: subject, sender and recipient addresses, dates, body, and attachment details, together with the record association the user chose.
- Uploaded content becomes part of your CRM data. The body (HTML) and attachments are held in FranConnect document storage — S3, with a write-once retention lock of 365 days applied at upload — and the metadata rows live in your tenant’s own database alongside the associated record.
- Upload activity logs are retained. Subject, message ID, provider, status, and associated records are kept for auditability.
Not kept: the user’s mailbox password; any message the user never opened or uploaded; drafts; and folders the user did not select.
8. Tenant Isolation
Credentials, configuration, and resulting access are tenant-specific, and additionally scoped per user. Nothing is shared between customers.
- Uploaded email records — physical separation. Email metadata written on upload goes to your tenant’s own database, resolved from the authenticated request’s tenant context on every connection. A query issued in one tenant’s context cannot address another tenant’s data.
- Service-side data — tenant and user keyed. Tokens, folder selections, connected-account details, retained messages, and upload logs are all stored and queried with the tenant ID and user number taken from the authenticated identity, never from request parameters.
- Per-user granularity. Each token is bound at Microsoft or Google to the individual user who consented; it cannot be used to reach another user’s or another customer’s mailbox.
Shared across tenants by design — these are FranConnect’s own assets and contain no customer credentials: the application registrations (client ID and secret) and the provider endpoint URLs.
9. Security Controls and Customer Control
| Control | Implementation |
| Revoke unilaterally | Microsoft: the user removes FranConnect under My Apps → Account → App permissions, or an administrator revokes it in Entra ID. Google: Google Account → Security → Third-party apps with account access. The next token use or refresh fails and the integration stops — no action is required by FranConnect. |
| Disable inside FranConnect | The user can log out of or remove the email provider configuration per user. The stored authorization is deactivated and no further provider calls are made for that user. |
| Scope limitation | Read-only mail scopes only — no send, no write, no administrative rights, no application permissions. |
| Consent model | Per user. No shared service account, and no account-wide or domain-wide grant. |
| Token rotation | Short-lived access tokens refreshed at roughly 75% of lifetime; each refresh replaces the stored tokens. |
| On-demand access only | Provider APIs are called only on live user actions. No background jobs or subscriptions touch the mailbox. |
| API authentication | The service is an OAuth 2.0 resource server; its functional endpoints require a valid signed JWT, and tenant and user identity are derived from that token. |
| Transport | All Microsoft Graph and Gmail API traffic uses HTTPS (TLS). |
10. How to Revoke FranConnect’s Access
You can disconnect the integration at any time, from either side.
From Microsoft (Outlook.com / Office 365)
- Sign in to your Microsoft account.
- Go to My Apps → Account → App permissions. An administrator can instead revoke the grant in Entra ID (Azure AD) under Enterprise applications.
- Locate the FranConnect application and remove it.
From Google (Gmail)
- Sign in to your Google Account.
- Go to Security → Third-party apps with account access.
- Locate FranConnect and remove access.
In both cases the next token use or refresh will fail and the integration stops working. No action is required by FranConnect.
From FranConnect
- Open the email configuration screen for the user.
- Log out of or remove the email provider configuration. The stored authorization is deactivated and no further provider calls are made for that user.
Because consent is per user, revoking one user’s access does not affect any other user’s connected mailbox.