Microsoft 365 mailbox

I run the practice

If your practice uses Outlook through Microsoft 365, start by choosing one of two paths:

• Yes, choose it now: use any shared or individual inbox reception already checks.
• Not yet, help me plan it: create a shared inbox, plan several inboxes, or ask IT to confirm which inboxes receive referrals.

Once an inbox is ready, Refera keeps one connection job with three recorded boundaries:

1. Organisation approved. A Microsoft administrator approves Refera for the organisation. This does not let Refera read an inbox.
2. Inbox access limited. The person who manages Exchange signs in separately and limits Refera to the chosen referral inbox. The two steps can be completed by the same person or by two different administrators.
3. Connection proved. Refera starts with the Inbox, proves the chosen mailbox is allowed and an unrelated mailbox is denied, then sends and receives a fixed connection email containing no patient information. Once the mailbox is connected, optionally keep the Inbox or choose one other folder. This uses the existing mailbox permission and needs no new Microsoft permission or administrator consent.

The inbox can be named reception@, referrals@ or anything else. An address typed in Refera is a choice, not authority to connect it; the mailbox object Microsoft returns is authoritative. Refera does not ask for a staff password, import old email or keep ongoing administrator access. New referral email starts from the recorded activation time. Disconnect stops that mailbox’s capture immediately and begins a separately verified Microsoft access-removal process.

A workspace may connect several referral mailboxes. Each mailbox is connected on its own, with its own approval session, Exchange scope, current folder, capture boundary, acceptance proof, poll health and disconnect lifecycle. Connecting or stopping one mailbox does not silently connect or stop another. Each additional mailbox repeats the separate approval and Inbox proof.

Stay signed in to Refera with your own individual work email. Enter the referral inbox, then use the one current action in Connections. If you do not manage Microsoft 365, copy that secure step to IT. Refera records a completed step, so another authorised administrator can finish without making the practice start over. Do not sign in with the shared referral inbox.

If your IT provider or Microsoft administrator needs the exact permissions, scope proof, expiry and rollback detail, continue to the administrator and security reference below.

Which account do I use?

One authorised person may be both the Refera owner and Microsoft approver. The referral inbox is only an intake source:

Role	Which address to use
Your Refera sign-in	Your own work email. Each staff member signs in separately.
Referral inbox	The shared or staff inbox that receives referrals. A shared inbox is not a sign-in. An individual staff inbox may use that person’s address, but every person still receives their own Refera account.
Organisation approval	A Microsoft administrator who can approve Refera for the organisation.
Inbox access	The person who manages Exchange for the practice. This can be the same administrator or a different person.

Drafting and sending are separate, optional permissions. They are off by default, require a separate Owner addendum and mailbox-scoped Microsoft grant, and every send requires a named staff member’s explicit approval. Refera never sends automatically.

Available on all plansIf the Microsoft connection service is unavailable, Refera keeps the saved inbox choice and says plainly that nothing was connected.

What access Refera receives

This is not a broad Microsoft 365 connection. Each Refera mailbox connection receives new messages from one exact mailbox and one selected folder, and nothing else. A workspace can hold several such independent connections.

• No staff password is shared with Refera.
• No offline_access permission or delegated refresh token is kept.
• Ongoing access uses a certificate, not a reusable customer secret.
• Read access is assigned in Exchange to the exact selected inbox.
• The separate discovery sign-in returns up to 500 normalised user and shared mailbox entries to the authorised Refera browser. Each entry contains the display name, primary address and recipient type, plus a derived opaque mailbox ID, whether it can be selected and a bounded reason when it cannot. No other directory field is exposed. The server-held list lasts only for the short setup session; it is never durably stored or logged. The discovery step grants no mailbox access or Refera connection, although Microsoft may record the organisation’s consent to the Refera application.
• The later mailbox approval resolves the selected primary address and one unrelated denial-control mailbox. Ongoing capture cannot browse the directory.
• Refera proves that a separate, not-already-authorised mailbox in the same tenant is denied before each new connection can activate.
• Connecting starts at a recorded time; it does not sweep old mail.
• The read-only connector cannot send, delete, move, mark as read or categorise mail.

The setup screen returning successfully is not treated as proof. Capture remains off until the mailbox boundary and a fixed connection email containing no patient information have both been verified end to end.

Before it changes Exchange, Refera checks the chosen inbox without changing anything. If Microsoft cannot find the inbox, Refera applies no access and returns the connection to an editable state. If the entered address is an alias, Microsoft returns its canonical primary inbox; Refera prefills that address for the Owner to confirm before a fresh attempt. The Microsoft organisation also needs one other existing shared or individual mailbox for the blocked-inbox check. Refera does not read mail from that second inbox; it uses only the primary address to prove the application cannot read it. If the chosen inbox is the organisation’s only mailbox, Refera applies no access and asks the practice to add any separate mailbox before retrying the same referral inbox. For a valid address, the preflight also reads the existing enterprise application, mailbox scope and role assignment, and stops before making a change if any name or boundary conflicts with the request.

If no suitable inbox exists

A dedicated referrals@ address is not required. The practice can nominate any existing shared or individual inbox that reception already monitors, such as reception@ or admin@.

If none is suitable, several inboxes are expected, or IT needs to confirm, choose Not yet, help me plan it, then choose the plan that matches the practice:

Create one shared inbox asks your Microsoft 365 administrator to create one practice-owned inbox and give the appropriate reception staff access. We use several inboxes keeps that fact in the setup plan so each real referral mailbox can be connected separately. Ask IT which inbox to use saves the workspace until IT confirms the address or addresses.

Refera remembers that plan across devices. It does not guess an address or create Microsoft users, mailboxes, routing rules or staff access. Every deferred route makes no connection, sends no Microsoft approval request and keeps referral capture off.

If referrals are split across several practice inboxes, do not connect one and assume the others are covered. Connect each mailbox separately. One Microsoft approval never widens itself into a batch grant, and Refera does not create mailboxes, routing rules or staff access. Run the patient-free Inbox acceptance path for each mailbox. After that mailbox connects, the Practice may optionally narrow capture to one folder.

Refera shows the exact selected address before Microsoft approval and never guesses the referral inbox from a Refera login, Microsoft administrator account or group address. The chosen inbox may be an individual staff inbox when the practice chooses it explicitly. You can disconnect, verify access removal and choose a different inbox later without widening the old mailbox boundary.

The Microsoft organisation must also contain an unrelated shared or individual mailbox that is not already authorised for the connection being created. Refera uses that address only to prove it cannot read outside the selected inbox. It does not read messages from the denial-control mailbox. If no safe control mailbox is available, setup stops without weakening the denial proof.

In short:

• existing shared inbox: enter its primary address;
• referrals already arrive at reception or admin: use that existing inbox; or
• several referral inboxes: connect each one separately and choose one folder in each; or
• no suitable inbox: save setup, create a shared inbox, then return and connect it.

Connect a mailbox

Sign in to Refera and open Connections. Choose Microsoft 365 and enter the primary address of the shared or staff inbox reception already checks. Select Continue with Microsoft, or copy the current secure step to IT through the practice’s normal trusted channel. Refera does not ask for an IT email address.

The first Microsoft step approves Refera for the organisation. The second Microsoft step is for the person who manages Exchange and creates the exact inbox boundary. Refera shows only the current step. If one person can do both jobs they can complete both. If the responsibilities are split, each administrator opens the secure step intended for them. Organisation approval grants no Mail.Read and does not let Refera read any inbox.

If Microsoft reports that the chosen address is an alias, group, distribution list or missing mailbox, Refera applies no inbox access. It offers the real Microsoft mailbox list so the practice can choose a user or shared mailbox. Text typed into that list’s search box never becomes authority to connect a different mailbox.

If the first administrator approved the wrong Microsoft organisation, choose Change Microsoft organisation in Connections. Refera retires any unfinished inbox link and forgets that organisation locally, then returns to the organisation-approval step. Admin consent was a real change in the mistaken organisation: an administrator of that organisation should also remove the Refera enterprise application or revoke its delegated Exchange.ManageV2 consent.

For inbox setup Refera creates a separate, ten-minute link bound to that one mailbox. Microsoft asks the person to choose an account instead of silently reusing an existing browser session. If that person cannot manage Exchange, Refera keeps the organisation receipt and offers a fresh inbox link for the right administrator. Nothing is read while another person is finishing that step.

Capture does not start on a chosen subfolder. Refera first proves the selected mailbox through its Inbox: the target mailbox is allowed, a separate not-authorised mailbox is denied, and the fixed patient-free connection email arrives. Only after that proof connects the mailbox can the Practice keep the Inbox or choose one other folder. Nested folders are shown with their path. The change uses the same mailbox-scoped permission, requires no new Entra permission or administrator re-consent, and keeps capture to exactly one folder so a moved message cannot be captured through overlapping folders. Refera reads one folder per mailbox.

To add another referral mailbox, return to Manage connected mailboxes and repeat the mailbox choice, separate approval sign-in and Inbox proof. There is no batch approval. A still-current discovery list may be reused for the mailbox choice; Refera never reuses a delegated token or one mailbox’s access or proof for another. The recorded organisation approval may be reused for another mailbox in the same Microsoft organisation, but every mailbox still needs its own inbox-access session and all three checks.

If the verified controller is unavailable or does not return a trusted Microsoft URL, the browser stays in Refera and says plainly that no connection or permission was created. The saved request remains available for retry or support. Do not put patient or referral information in the setup request.

Refera does not send the per-mailbox approval to the chosen referral inbox. The Microsoft page opens directly in the same browser. If that page is closed or its 10-minute session expires, open Connections and choose Continue with Microsoft. Refera first retires the unused attempt, then opens a newly bound Microsoft session. If another person administers Microsoft 365, choose Copy secure link for IT and send them that short-lived, request-bound link through the practice’s normal trusted channel. After administrator approval and the positive and negative mailbox checks, Refera automatically sends active workspace owners and admins a fixed connection email that names the chosen inbox and contains no patient information.

After Microsoft finishes, the administrator sees a bounded completion receipt with no practice or mailbox contents. The practice owner’s open Connections screen refreshes that mailbox’s setup state automatically; a manual reload is not required.

Microsoft administrators approve the organisation and exact-inbox steps in Microsoft; Refera records each receipt and completes the safe connection checks automatically.

I manage Microsoft 365

Microsoft may show a verified publisher badge for Refera. That badge is a useful trust signal, but it is separate from the mailbox boundary and connection checks. Until that badge is present, Microsoft’s risk checks or the customer’s tenant policy may block approval even when the administrator has the right role. Refera cannot override that compatibility limit. If Microsoft marks Refera as Unverified, the administrator may continue only when the organisation’s own policy permits it. If Microsoft blocks the request, do not work around that policy: copy the Refera connection receipt to [email protected] or ask the organisation’s Microsoft administrator to review it.

The organisation-approval step needs an Entra role or custom authority permitted to grant administrator consent for delegated Exchange.ManageV2. The inbox step needs the Microsoft Entra Exchange Administrator role and membership in Exchange Online’s Organization Management role group, or equivalent delegated authority that can assign Application RBAC permissions. The same account may hold both. Refera also supports the two responsibilities being held by different administrators, without redoing a completed organisation approval.

The permission is limited to one mailbox

Refera uses Exchange Online RBAC for Applications, Microsoft’s replacement for legacy Application Access Policies. The assignment is:

• role: Application Mail.Read;
• resource scope: the exact nominated referral mailbox; and
• identity: Refera’s certificate-backed application, not a staff account.

There must be no separate tenant-wide Mail.Read application grant in Microsoft Entra. Microsoft treats Entra grants and Exchange Application RBAC grants as additive, so an unscoped grant would defeat the mailbox boundary and Refera treats that as a failed setup.

Before capture can be called connected, Refera’s launch checks require the nominated mailbox to be in scope, a different mailbox in the same tenant to be out of scope, and one fixed connection message containing no patient information to arrive through the capture pipeline. A returned Microsoft consent screen is not enough.

After activation, Connections shows the last successful inbox check. Refera records that timestamp only after the message sync completes and a second exact check confirms that the poll still belongs to the current mailbox connection. If that timestamp becomes stale, the card changes to Inbox check delayed, keeps the exact mailbox and the boundary verified at activation visible, and retries automatically. It does not continue to present an old green Connected state. Refera also attempts one metadata-only delayed-check email to active workspace owners and admins after the same 10-minute threshold. Refera does not repeat that warning while the same interruption continues. At first detection, Refera freezes the owner and admin recipient set and keeps one metadata-only recovery watch keyed by a one-way hash for each person, without storing their email address in that watch. A recovery receipt remains blocked unless the provider accepts the warning for every person in that original set. When a fresh same-connection check completes within 24 hours, Refera attempts one recovery receipt for each warned person who is still an active owner or admin. It does not send that recovery to someone removed from the role or added after the warning. Provider acceptance is not proof of mailbox delivery. Both messages name only the practice, connected inbox, check time and administrative status. They contain no patient, referral, message subject, sender or document information and do not claim that an individual email was delivered or missed. The timestamp does not repeat the separate control-inbox denial proof or assert that a Microsoft administrator has made no later permission change.

After the assignment is applied, Refera allows up to 2 hours 15 minutes for Exchange RBAC to propagate. During that window it repeatedly proves that the nominated mailbox is allowed and the unrelated control mailbox is denied. It does not send the test message or start the delivery timer until both scope checks pass. It then starts a separate 30-minute delivery-check window. The two clocks are not combined, so slow Microsoft propagation cannot consume the delivery check.

Settings records and displays the exact non-secret enterprise application, mailbox-scope and role- assignment names, together with Application Mail.Read. If an apply result is uncertain or a later proof fails, capture stays off and the connection enters Setup cleanup required. Refera does not claim that permission was absent or removed; those exact named resources remain visible for review and removal before another connection attempt.

This is the practical result: Refera can read the referral mailbox and cannot use this permission to read staff mailboxes, calendars, contacts, files or directory content.

Manage mailboxes and folders

The Practice can connect several mailboxes. Each row in Manage connected mailboxes names the mailbox, selected folder, connection state and last successful check. A delayed check affects that mailbox’s state and does not turn another mailbox red or stop it polling.

To change the folder, open that mailbox and choose one folder from Microsoft’s current list. The change is stored on the same mailbox slot and reaches the poll configuration before the new folder is treated as active. It does not require a new permission or administrator re-consent.

To replace a mailbox, disconnect that mailbox, wait for Refera to verify that Microsoft denies the old access, then connect the replacement through a fresh short approval. Stopping one slot leaves other connected mailboxes polling. The old boundary is never silently widened or carried over.

A connection created before mailbox slots existed remains readable under its original record key and defaults to Inbox. Refera does not silently rewrite it into a new slot. It must finish its own disconnect or relink lifecycle on that original key before new slot behaviour can replace it.

Within one Microsoft directory, an exact mailbox can be claimed by only one Refera workspace at a time. A denial-verified disconnect releases that claim. The same written address in a different Microsoft directory is a different mailbox identity.

Separate short administrator sessions, no ongoing delegated access

Each bounded step uses one short Microsoft sign-in, but discovery and per-mailbox approval are separate administrator sessions. Each link is valid for exactly 10 minutes. Discovery uses delegated Exchange.ManageV2 only to list the bounded mailbox directory. It grants no mailbox access or Refera connection, although Microsoft may record the organisation’s consent to the Refera application. The later approval uses that consent to create and verify the mailbox-scoped Exchange assignment. Each additional mailbox needs a fresh approval session.

Neither session requests offline_access. Refera rejects any response containing a refresh token, keeps the access token only in process memory and discards it when that step finishes. These administrator sessions are not how mail is collected. Ongoing capture uses app-only client credentials with an X.509 certificate and the mailbox-scoped Application Mail.Read assignment. Refera does not ask for a customer-created client secret or a staff password.

New mail only

Activation records a fixed capture from time. The normal poller reads messages received at or after that boundary, using a cursor and idempotent processing so reconnecting cannot silently move the boundary backwards. It does not sweep the existing inbox or import older mail.

A historical import would be a separate, explicitly agreed and bounded job. Connecting the live mailbox never starts one. The least-privilege poller is read-only: it does not delete, move, mark as read or categorise messages, so the practice mailbox remains the original record.

Drafting and sending stay separate

Read-only capture does not enable writing or sending. Outlook draft creation remains a separate future capability. The optional human-approved sending service is implemented behind an independent release and connection check; it remains unavailable to a practice until every control below is active.

Capability	Microsoft permission	Current state
Copy-ready text inside Refera	None	Available for a staff member to copy into Outlook
Create an Outlook draft	mailbox-scoped Application Mail.ReadWrite	Separate optional permission, off by default and not currently enabled
Send one fixed patient-booking email after a named person approves	mailbox-scoped Application Mail.Send	Implemented, off by default and unavailable until the separate permission and checks are complete

Neither optional permission can be inferred from Mail.Read. Each has its own request, mailbox scope, unrelated-mailbox denial and a connection check before it can become active. Refera never sends automatically.

How the optional sending tier works

An Owner first accepts a separate sending addendum after a recent passkey or TOTP check. The Owner also chooses whether each message may be approved by any authorised staff member, by Owners and Admins, or by the Owner only. Accepting the addendum does not grant Microsoft access.

Microsoft sending becomes available only after a separate Exchange administrator action assigns Application Mail.Send to Refera’s certificate-backed identity through Exchange Application RBAC for the exact nominated mailbox. The patient-free test send is restricted to that exact nominated mailbox. The nominated mailbox must be allowed, an unrelated control mailbox must be denied, and a non-clinical connection send must pass. Refera does not add an unscoped Entra Mail.Send application permission.

For each real message, a signed-in staff member reviews one fixed server-generated patient-booking email and explicitly chooses Confirm and send email. Refera binds the exact tenant, referral, sender mailbox, recipient hash, subject hash, body hash, empty attachment set, staff identity and role, sealed draft approval, addendum and permission generation into one short-lived, single-use operation. Attachments are not supported in this tier.

Microsoft Graph returning 202 Accepted means Microsoft accepted the request for processing. It does not prove delivery, reading or booking. If the browser loses the response, Refera resolves only the original request identifier against the durable operation record. If the outcome remains ambiguous, Refera records Outcome unknown, never retries automatically and requires staff to check Outlook Sent Items before making a fresh decision. Re-sending content Microsoft already accepted requires a new sealed draft approval plus a separate explicit repeat-send confirmation.

A refused or unknown outcome triggers durable PII-free operational alerts through both Slack and email. Accepted sends remain in the practice audit trail without a routine success alert.

The Owner can disable the addendum without disturbing read-only capture. Local sending stops immediately, but Settings continues to show Microsoft removal required until the separate Application Mail.Send assignment is removed and target-mailbox denial is independently proved.

Disconnecting

For an activated connection, an Owner or Admin opens Connections, chooses Stop reading for the mailbox and confirms. Refera first requires the practice poller to confirm a durable local stop.

Because Refera keeps no delegated refresh token, Exchange administration does not persist after setup. A Microsoft 365 administrator must remove the Exchange Application RBAC assignment. Refera shows the exact assignment and scope names and provides Copy instructions for IT for that bounded handoff. Refera then verifies that mailbox access is denied. Until that denial is proved, Settings says Revocation pending, keeps reconnect blocked and labels capture Removal pending rather than claiming the permission was revoked. If the poller cannot confirm that it stopped, Settings reports the failure and leaves the record unchanged.

Disconnecting stops new capture. It does not delete records already held in Refera; export and account closure are separate controls. Any optional draft or send assignment would also require its own removal and denial proof.

Availability and the fail-closed path

The public flow implements the self-service handoff, but the API returns an approval URL only when the complete controller is configured. That includes the validated callback, Exchange RBAC orchestration, connection checks and independent local-stop control. A disabled or incomplete controller returns no URL and changes no Microsoft connection state. The onboarding screen preserves the concierge request, reports the failure and keeps capture off.

When enabled, Connections starts each bounded approval and shows the current receipt. Settings is status-only and links back to Connections. Refera does not show Capture connected until all three connection proofs pass. Real referral capture still requires the separate go-live review.

For technical background, see Microsoft’s documentation for Exchange Online RBAC for Applications, testing a service principal’s mailbox scope, and certificate credentials.

Related

• Signing up
• Preparing to go live
• What your IT needs to grant