Microsoft 365 Mailboxes

Exchange Online mailboxes through Microsoft Graph: the four mailbox types and how they differ, message listing and search, inbox rules, out-of-office and forwarding, mailbox size and quota, shared-mai

SKILL.md

GitHub

Microsoft 365 Mailbox Management

Overview

Microsoft 365 mailboxes are managed through Exchange Online, accessible via Microsoft Graph. For MSPs, mailbox tasks range from diagnosing delivery failures and searching for lost emails to managing shared mailboxes and offboarding users. Graph provides a unified API across all mailbox types.

Anti-triggers

  • "The email never arrived" — most often the message was quarantined or blocked before Exchange, so nothing here will find it. Check the mail-security gateway first: mimecast, spamtitan, abnormal, ironscales, or the email-security pack. Come back here only once you know the message reached the tenant.
  • Mailbox permissions and forwarding across tenants — full-access delegation and forwarding rules are CIPP primitives with proper multi-tenant scope; use the cipp plugin (cipp-mailboxes).
  • A suspicious forwarding rule as an active compromise — this skill reads rules; interpreting them as an indicator, plus session revocation and the rest of the response, is m365-security.
  • Recovering a permanently deleted mailbox or item — past the retention window this is a backup restore, not a Graph read; use the backup-pack or kaseya/datto-saas-protection.

Mailbox Types

Type Description Common MSP Tasks
User Mailbox Standard licensed user Search, out-of-office, size, rules
Shared Mailbox Team inbox, no license required Access management, forwarding
Room/Equipment Calendar resource booking Availability, booking policies
Distribution Group Email alias to multiple users Membership, send-as

Graph API Patterns

List a User's Emails

GET /v1.0/users/{userId}/messages?$select=id,subject,from,receivedDateTime,isRead&$top=25&$orderby=receivedDateTime desc

Search for a Specific Email

GET /v1.0/users/{userId}/messages?$search="subject:invoice 2024"&$select=id,subject,from,receivedDateTime

Also supports KQL search operators:

  • $search="from:john@example.com" — by sender
  • $search="subject:urgent hasAttachments:true" — combined
  • $search="received>=2024-01-01" — date range

Get Message Details (with body)

GET /v1.0/users/{userId}/messages/{messageId}?$select=id,subject,from,body,receivedDateTime,attachments

Get Mailbox Settings (out-of-office, timezone)

GET /v1.0/users/{userId}/mailboxSettings

Response:

{
  "automaticRepliesSetting": {
    "status": "disabled",
    "internalReplyMessage": "",
    "externalReplyMessage": ""
  },
  "timeZone": "Eastern Standard Time",
  "language": { "locale": "en-US" }
}

Set Out-of-Office Reply

PATCH /v1.0/users/{userId}/mailboxSettings
Content-Type: application/json

{
  "automaticRepliesSetting": {
    "status": "alwaysEnabled",
    "internalReplyMessage": "<html>I'm out of office until Jan 15.</html>",
    "externalReplyMessage": "<html>I'm out of office. For urgent matters contact support@company.com.</html>"
  }
}

Disable Out-of-Office Reply

PATCH /v1.0/users/{userId}/mailboxSettings
Content-Type: application/json

{
  "automaticRepliesSetting": { "status": "disabled" }
}

Get Mailbox Usage / Size

GET /v1.0/users/{userId}/mailFolders/inbox?$select=totalItemCount,sizeInBytes

For full mailbox statistics (requires Exchange admin permissions):

GET /v1.0/reports/getMailboxUsageDetail(period='D7')

Get Inbox Rules

GET /v1.0/users/{userId}/mailFolders/inbox/messageRules

Response shows rules that may affect mail delivery:

{
  "value": [
    {
      "id": "rule1",
      "displayName": "Move newsletters",
      "conditions": { "senderContains": ["newsletter"] },
      "actions": { "moveToFolder": "Newsletters" },
      "isEnabled": true
    }
  ]
}

Send an Email on Behalf of a User

POST /v1.0/users/{userId}/sendMail
Content-Type: application/json

{
  "message": {
    "subject": "Your IT support request has been resolved",
    "body": { "contentType": "HTML", "content": "<p>Your ticket #1234 is now closed.</p>" },
    "toRecipients": [{ "emailAddress": { "address": "user@contoso.com" } }]
  },
  "saveToSentItems": true
}

Shared Mailbox Management

Add User Access to Shared Mailbox

Shared mailbox access is managed via Microsoft 365 admin or Exchange PowerShell, not directly via Graph mailbox endpoints. Use Graph group membership or delegate access patterns.

List Users With Shared Mailbox Access

Access is represented as mailboxPermissions — check via admin APIs or Exchange PowerShell:

Get-MailboxPermission -Identity "sharedmailbox@contoso.com" | Where-Object { $_.AccessRights -eq "FullAccess" }

Mail Flow Diagnostics

Check Recent Delivery Failures

Look for NDRs (Non-Delivery Reports) in the user's inbox or sent items:

GET /v1.0/users/{userId}/messages?$filter=senderEmailAddress/address eq 'postmaster@domain.com'&$select=subject,receivedDateTime,body

Common Delivery Failure Reasons

NDR Code Meaning Resolution
5.1.1 Recipient doesn't exist Verify UPN / check aliases
5.1.8 Sender blocked (spam) Review anti-spam policy
5.2.2 Mailbox full Check quota, remove items
5.7.1 Unauthorized relay SMTP auth settings
5.7.606 Sender IP blocked Submit to Microsoft for delisting

Common MSP Workflows

Lost Email Investigation

  1. Confirm exact sender address and approximate date
  2. Search user's mailbox including Junk and Deleted folders
  3. Check inbox rules that might divert messages
  4. Review message trace in Microsoft 365 admin (requires admin access)
  5. Check anti-spam quarantine if IT admin access available

Offboarding Mailbox Handling

Option A: Convert to shared mailbox (no license needed, data accessible)

  1. Disable user account
  2. Convert mailbox to shared via admin center or Graph
  3. Grant departing user's manager full access

Option B: Forward and archive

  1. Set auto-forward to manager
  2. Export mailbox to PST/archive
  3. Remove license after retention period

Option C: Auto-reply and close

  1. Set out-of-office explaining user has left
  2. Leave mailbox active during handover period
  3. Remove license after business decides archival approach

Error Handling

Error Cause Resolution
MailboxNotEnabledForRESTAPI User has no Exchange license Assign Exchange/M365 license
ErrorItemNotFound Message ID expired or moved Search by subject/date instead
AuthenticationError Token expired Re-authenticate via OAuth flow
TooManyRequests Graph throttling (429) Retry with exponential backoff
Forbidden (403) Missing Mail.Read permission Check app registration

Permissions Required

Task Microsoft Graph Permission
Read emails Mail.Read or Mail.ReadWrite
Send email Mail.Send
Mailbox settings MailboxSettings.ReadWrite
All users' mail (admin) Mail.Read (delegated + admin consent)

Related Skills