# Mail access for the whole organisation

For the assistant to read mail and write drafts, it needs access to the
mailbox. The simplest way for an organisation with several mailboxes is an
**app registration**: one access for the whole organisation, with no
per-mailbox sign-in. Registrations are in Organisation → **Integrations**, the
**Mail access for the whole organisation** card. The organisation's owners and
managers manage them.

For a single mailbox, a **connected account** (the Connect Outlook / Connect
Gmail button) or an **IMAP login** works instead — see the guide
[Adding and connecting a mailbox](/en/admin/adding-a-mailbox).

## Microsoft 365 (Entra)

You need admin rights in Entra ID to set it up.

1. https://entra.microsoft.com → Identity → Applications → **App registrations**
   → **New registration**.
2. Name it `draften`, say, **Accounts in this organizational directory only**,
   no redirect URI → **Register**.
3. On **Overview**, note the **Application (client) ID** and the **Directory
   (tenant) ID**.
4. **Certificates & secrets → New client secret** (24 months at most). The value
   is shown only once; note the expiry date too.
5. **API permissions → Add a permission → Microsoft Graph → Application
   permissions**: `Mail.ReadWrite` and `MailboxSettings.ReadWrite` (the second
   only for the colour of the Outlook category).
6. **Grant admin consent** — green ticks on both rows.

**Do not add `Mail.Send`.** draften sends nothing, and without that permission
it cannot — which is the point.

Then in draften choose **Microsoft 365 (Entra)** in the registrations card,
fill in a name, the Directory (tenant) ID, the Application (client) ID, the
secret's value (not its ID) and its expiry, and click **Add registration**.

## Google Workspace

1. Enable the **Gmail API** in your Workspace's Google Cloud project.
2. Create a **service account** and download its **JSON key** (IAM → Service
   accounts → Keys).
3. In Google Admin → Security → Access and data control → API controls →
   **Domain-wide delegation**, allow the service account's numeric client ID
   for the scope `https://www.googleapis.com/auth/gmail.modify`.

In draften choose **Google Workspace**, upload the key file and add the
registration. It is stored encrypted; only the account's e-mail and client ID
are shown.

## Assigning it to mailboxes

A registration connects nothing by itself. The **organisation owner** assigns
it to each mailbox on its page: Mail access → **Use** → **Apply**, and runs
**Test the connection**. The registration shows which mailboxes use it. With
[mailbox automatically](/en/admin/member-sign-in) on, a new mailbox is bound by
itself when exactly one registration is active for its mail system.

## Secret expiry

An Entra registration's secret has a limited validity. Before it expires,
create a new one in Entra and click **New secret** at the registration in
draften. When a secret expires, the mailboxes disconnect (`invalid_client`)
and the assistants skip them; after replacing it, run the connection test.

## Technically narrowing the access (optional)

A Microsoft 365 registration reaches every mailbox of the organisation; draften
is the guard (a member cannot add a mailbox; the assistant never sends or
deletes). Whoever wants a technical fence as well narrows the application to a
security group with an `ApplicationAccessPolicy` in Exchange Online:

```
Connect-ExchangeOnline -UserPrincipalName admin@<tenant>.onmicrosoft.com
New-DistributionGroup -Name "draften - allowed mailboxes" -Alias draften-mailboxes -Type Security -Members mailbox@company.com
New-ApplicationAccessPolicy -AppId <Application (client) ID> -PolicyScopeGroupId draften-mailboxes@company.com -AccessRight RestrictAccess -Description "draften: allowed mailboxes only"
Test-ApplicationAccessPolicy -Identity mailbox@company.com -AppId <Application (client) ID>
```

Every further mailbox then has to be added to the group too, or its connection
test fails with 403 (`AppOnly AccessPolicy`). The policy can take several hours
to take effect.