Quick introduction to relevant Planhat capabilities
Planhat is a customer platform to which you sync customer-related data from multiple systems and run customer workflows. One of our oldest and most widely used native integrations is the Outlook integration, used for syncing and sending personal emails and syncing calendar events.
Outlook is used for sending “personal emails”: they go out from the personal email address linked to the Outlook account (eg, daniel@planhat.com) and should be used for personal service communications with customers. For “marketing” communication, which is typically higher-volume (potentially >thousands per day) and impersonal, customers use our “Transactional emails” via Planhat’s Sendgrid account (which is not covered by this article).
Our latest Outlook integration version, used both for email and calendar functionality, was released in 2022 and is based on Microsoft Graph API v1. Internally, the Planhat application uses the Microsoft Nodejs package (msgraph-sdk-javascript) to interact with the Microsoft Graph API. In the sections below, we’ll describe technical security capabilities (eg, authentication scopes) and operational security capabilities (eg, email filtering, power tools).
Separately, you can read about our general security policies (eg, SOC 2 Type II, penetration testing, etc).
User Authentication and Permissions
Access Type
Planhat grants access to email and calendar (each individually) and on a per-user basis, not for the entire organisation. Each user grants access to specific folders. This gives each employee a high degree of control over their mail and calendar, and reduces organisational security risk by removing a single-point-of-failure.
However, admins have control over which roles have access to enabling Email and Calendar at all.
Scopes and permissions are based on the OAuth 2.0 authorisation protocol used across the Microsoft Identity Platform.
Scopes for Emails
Planhat is granted access to 4 scopes, as shown when each user authorises the sync:
Read your profile (user.read)
Maintain access to data you have given Planhat access to (offline_access)
Read your mail (mail.read)
Send mail as you (mail.send)
Scopes for Calendar
Planhat is granted access to 3 scopes, as shown when each user authorises the sync:
Read your profile (user.read)
Maintain access to data you have given Planhat access to (offline_access)
Have full access to your calendars (calendars.readwrite)
Syncing emails and calendar events
Filters and permissions
Planhat, per the scopes, maintains full access to the user’s mail and calendar. However, for practical security purposes, the application maintains a three-step “filter and permission” sequence to ensure only the right individual(s) can access this data:
Domain matching: only sync over mail/events where the contact (or “enduser” in Planhat) has an email address that matches a “Related domain” of a company. This “Related domain” is a controllable property of the company. This ensures that private correspondence with a partner, or lawyer, or between colleagues, does not get synced over (more technically, does not get synced over and saved to Planhat’s database).
Email filtering: specifically for emails, the application can filter the sync based on specific email participants and/or email content. Some real-world examples we’ve supported: a) the pension advisor of employees is also a customer, so it was required to block out emails from a specific group of people from the customer when it contained certain content related to employee pension plans, b) block out any communication between a user CEO and a customer CEO, or c) the partner of a user works at a customer so block out their correspondence
General permission controls: once inside the application, Planhat has a three-layered permission structure for data. Each user’s access to data can be controlled based on a) portfolio permissions (eg, I can only see data for companies I own), b) object-and-property-level permissions (eg, I can see that there have been emails, but not the subject line; or I can’t see company ARR), and c) workflow permissions (eg, I can not access the Shared Inbox)
By combining these three, administrators can ensure that only the authorised users can access specific emails and calendar events.
When first set-up, Planhat syncs emails up to 360 days back (the number of days is a controllable tenant setting, and can be set to 0 if no historical emails are to be synced at initial authentication). Mail and calendar are then synced on a 10min job.
Power tools related to emails
At any point, each user can:
Delete an email that has been synced (and it won’t sync back)
Revoke account access (blocking future syncs)
Remove all personal emails synced over historically
Admins can also revoke account access and remove all personal emails for a specific user, available as a power tool in case of emergencies.
These actions will not impact anything on in Outlook, only remove it from Planhat’s database.
Sending personal emails with Outlook
“Personal Emails” sent from Planhat are sent from the user’s Outlook by calling the API. When sent from Planhat, either manually/one-off or from an automated sequence, they appear in the “Sent” folder on the Outlook side and any reply will show up in Outlook and then synced over to Planhat.
To ensure deliverability, there are three tenant settings related to mails:
Automatic Emails User Daily Limit: how many automatic emails can we send daily before we queue up emails for the next day
Email content size: what size of emails can we send, default limit is 2MB and max is 8MB
Do not Disturb hours: to ensure customers are not sent automatic emails at inconvenient or obviously-automated hours