> For the complete documentation index, see [llms.txt](https://docs.realmjoin.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.realmjoin.com/automation/runbooks/runbook-references/user/mail/delegate-full-access.md).

# Delegate Full Access

Grant or remove full access to this user's mailbox

### Description

Grants one or more people full access to the mailbox of this user, or removes that access again. Optionally the mailbox opens automatically in the delegates' Outlook. The permissions are shown before and after the change, and a failure for one delegate does not stop the others.

### How it works

On each run the runbook:

1. Connects to Exchange Online with the Automation account's managed identity.
2. Verifies that the selected mailbox owner (`UserName`) actually has a mailbox - if not, the run stops before anything is changed.
3. Resolves every selected delegate to its primary SMTP address and drops duplicates and the mailbox owner itself.
4. Reads and prints the current **FullAccess** delegations on the mailbox (the *status quo*).
5. Grants or removes FullAccess for each remaining delegate, one at a time.
6. Re-reads the mailbox permissions and prints the resulting state plus a per-run summary.

The runbook only ever touches the **FullAccess** right on the one selected mailbox. Send As, Send on Behalf and folder-level permissions are not affected.

#### Selecting delegates

The **Delegate access to** field is a **multi-select** user picker. Select as many delegates as needed - all of them receive the same action (*Grant access* or *Remove access*) and the same AutoMapping setting from the form in a single run.

The picker is restricted to member accounts (`userType eq 'Member'`), so guest accounts are not offered. It hands over each selected delegate as a **user principal name**, so the very first log line already reads as a list of UPNs instead of raw object IDs. Each value is then resolved against Exchange Online, and from the preflight step onward all output shows the delegate's primary SMTP address.

Two picker entries that resolve to the same mailbox are de-duplicated, and a delegate that resolves to the mailbox owner is dropped with a warning - a mailbox cannot be delegated to itself.

#### What gets changed

* **Grant access (`Remove` = false):** `Add-MailboxPermission` with `-AccessRights FullAccess` for each delegate.
* **Remove access (`Remove` = true):** `Remove-MailboxPermission` with `-AccessRights FullAccess -InheritanceType All` for each delegate.

#### AutoMapping

**`AutoMapping`** is only evaluated when granting access; the portal hides the field when *Remove access* is selected. With AutoMapping enabled, Outlook adds the delegated mailbox to the delegate's profile automatically - but only after the client re-creates the mapping, which can take a while. Existing grants are not re-written to change their AutoMapping value; remove the delegation and grant it again if the mapping behaviour must change.

#### Idempotent by design

Nothing is done twice and nothing fails just because it was already true:

* Granting access to a delegate who already holds FullAccess is reported as *unchanged*, not as an error.
* Removing access from a delegate who has no FullAccess entry is reported as *unchanged*, not as an error.
* When the pre-change snapshot cannot classify an existing permission entry, the runbook does **not** take the shortcut - it calls Exchange Online and lets its response decide, so a removable delegation is never silently skipped.

#### Partial results

Delegates are processed independently:

* A delegate **without a mailbox** is skipped during the preflight check and counted as *skipped*; the remaining delegates are still processed. If none of the selected delegates has a mailbox, the run stops.
* A delegate whose change **fails** is reported with a targeted reason (directory-replication delay, insufficient Exchange Online permissions on the managed identity, a permission inherited from a group, or a shared/unlicensed mailbox) and the loop continues with the rest.

Every run ends with a summary line in the form `Summary: <changed>, <unchanged>, <failed>, <skipped (no mailbox)>`, followed by the resulting FullAccess delegations on the mailbox.

If **any** delegate failed, the runbook itself reports a failure. This is deliberate: with a multi-select picker, a partial success reported as a clean run would hide delegates that never received access.

#### Limitations

* **Inherited permissions cannot be removed.** A FullAccess right that comes from a role group or security group membership is shown as *inherited* but cannot be revoked here - adjust the group membership or role assignment instead.
* **Only explicit Allow grants are managed.** An explicit **Deny** entry on the mailbox is displayed for transparency, but the runbook never adds or removes one.

#### Prerequisites

The Automation account's managed identity connects to Exchange Online via `Connect-RjRbExchangeOnline` and needs:

* the `Exchange.ManageAsApp` application permission on *Office 365 Exchange Online*, and
* the **Exchange Administrator** role (or an equivalent Exchange Online RBAC role that includes `Add-MailboxPermission` and `Remove-MailboxPermission`).

The runbook makes no Microsoft Graph calls - the user picker is a portal-side annotation only, so no Graph application permissions are required.

### Location

User → Mail → Delegate Full Access

**Full Runbook name**

rjgit-user\_mail\_delegate-full-access

### Details

| Property         | Value                                                                             |
| ---------------- | --------------------------------------------------------------------------------- |
| Version          | 1.1.3                                                                             |
| Required modules | <p>RealmJoin.RunbookHelper (>= 0.8.10)<br>ExchangeOnlineManagement (>= 3.9.2)</p> |
| Schedulable      | no                                                                                |

### Permissions

#### Application permissions

* **Type**: Office 365 Exchange Online
  * Exchange.ManageAsApp
    * *Manages FullAccess mailbox delegations in the app-only Exchange Online session*

#### RBAC roles

* Exchange Administrator
  * *Required for the app-only Exchange Online session managing FullAccess permissions*

### Parameters

#### UserName

User principal name of the user the runbook acts on. Set by the portal from the selected user.

| Property         | Value                                  |
| ---------------- | -------------------------------------- |
| Required         | true                                   |
| Default Value    |                                        |
| Type             | String                                 |
| Hidden in portal | yes (preset via runbook customization) |

#### delegateTo

People who get or lose full access. You can pick several at once.

| Property            | Value              |
| ------------------- | ------------------ |
| Required            | true               |
| Default Value       |                    |
| Type                | String\[]          |
| Portal display name | Delegate access to |

#### Remove

Grant gives the selected people full access, Remove takes it away.

| Property            | Value   |
| ------------------- | ------- |
| Required            | false   |
| Default Value       | False   |
| Type                | Boolean |
| Portal display name | Action  |

**Portal options**

| Portal option | Value |
| ------------- | ----- |
| Grant access  | false |
| Remove access | true  |

#### AutoMapping

Makes the mailbox appear automatically in the delegates' Outlook. Has no effect when access is removed.

| Property            | Value                                     |
| ------------------- | ----------------------------------------- |
| Required            | false                                     |
| Default Value       | False                                     |
| Type                | Boolean                                   |
| Portal display name | Map the mailbox in Outlook automatically? |

[Back to Runbook Reference overview](/automation/runbooks/runbook-references.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.realmjoin.com/automation/runbooks/runbook-references/user/mail/delegate-full-access.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.