Skip to content

Configuring the Microsoft 365 Email Outbox Tool

Introduction

The Microsoft 365 Email Outbox tool allows your AI agents to send emails from a Microsoft 365 (Exchange Online) mailbox. Agents can compose messages with To/Cc/Bcc recipients, plain-text bodies or reusable HTML templates with variables, and PDF attachments.

The tool connects to Microsoft through the Microsoft Graph API using app-only OAuth (the client credentials flow). This means:

  • No user password is stored. The tool authenticates with an application identity you create in Microsoft Entra ID, not with a mailbox password.
  • It works with MFA and Security Defaults enabled. Because there is no interactive login, multi-factor authentication policies do not affect it.
  • It is the supported long-term path. Microsoft is retiring Basic authentication (username/password) for SMTP submission in Exchange Online: per Microsoft's updated timeline, it is disabled by default for existing tenants from the end of December 2026 (administrators can temporarily re-enable it), newly created tenants start without it, and Microsoft will announce the final removal date in the second half of 2027. This tool is not affected by that retirement.

Setting it up has two parts: first an administrator prepares an app registration in your Microsoft tenant, then you enter its credentials in Wabee Studio.

Prerequisites

Before configuring the tool, ensure you have the following:

  1. Access to the Wabee tool management dashboard
  2. A Microsoft 365 tenant with an Exchange Online mailbox to send from (a licensed user mailbox or a shared mailbox)
  3. A Microsoft administrator able to create an app registration and grant admin consent for an application permission (typically a Global Administrator)

Part 1: Configure Microsoft Entra ID

These steps are performed by your Microsoft 365 administrator in the Microsoft Entra admin center (or in the Azure portal under Microsoft Entra ID — the pages are the same).

Step 1: Create an app registration

  1. In the Entra admin center, open App registrations and click New registration
  2. Give it a recognizable name, for example Wabee Email Outbox
  3. Under Supported account types, keep the default Accounts in this organizational directory only (single tenant)
  4. Leave Redirect URI empty — this integration has no interactive login
  5. Click Register

On the app's Overview page, copy these two values — you will enter both in Wabee Studio later:

  • Application (client) ID
  • Directory (tenant) ID

Step 2: Grant the Mail.Send application permission

  1. In the app registration, open API permissions and click Add a permission
  2. Select Microsoft Graph
  3. Select Application permissions — not Delegated permissions. Delegated permissions only work with a signed-in user and will not work with this tool.
  4. Search for and check Mail.Send, then click Add permissions
  5. Back on the API permissions page, click Grant admin consent for <your organization> and confirm

Admin consent is required

The Status column must show a green check mark ("Granted for <your organization>") next to Mail.Send. Without admin consent, the tool authenticates successfully but every send fails with an authorization error.

Step 3: Create a client secret

  1. In the app registration, open Certificates & secrets and click New client secret
  2. Enter a description (for example wabee-outbox) and choose an expiration period
  3. Click Add, then immediately copy the Value column — it is shown only once

Copy the Value, not the Secret ID

The Certificates & secrets page shows both a Value and a Secret ID. Wabee needs the Value. Also note the expiration date: when the secret expires, sending stops working until you create a new secret and update the tool configuration.

By default, the Mail.Send application permission allows the app to send email as any mailbox in your tenant. To limit it to only the intended sender mailbox(es), an Exchange administrator can create an application access policy in Exchange Online PowerShell:

# One-time: create a mail-enabled security group and add the allowed
# sender mailbox(es) to it, then scope the app to that group.
New-ApplicationAccessPolicy `
  -AppId "<application-client-id>" `
  -PolicyScopeGroupId "<mail-enabled-security-group-address>" `
  -AccessRight RestrictAccess `
  -Description "Restrict Wabee Email Outbox to approved sender mailboxes"

# Verify: should return AccessCheckResult 'Granted' for the sender
# mailbox and 'Denied' for any other mailbox.
Test-ApplicationAccessPolicy -AppId "<application-client-id>" -Identity "sender@yourdomain.com"

Policy changes are cached and can take anywhere from 30 minutes to about 2 hours to be enforced, depending on how recently the app has called the API — and the test cmdlet bypasses this cache, so it can report the new result before enforcement catches up. Allow for this window before concluding that a policy isn't working.

Application access policies vs. RBAC for Applications

Microsoft's newer RBAC for Applications mechanism replaces application access policies going forward: it achieves the same restriction with an Application Mail.Send role assignment scoped to a management scope or administrative unit (in which case the unscoped Entra-level Mail.Send consent should be removed). Existing application access policies keep working, and remain the simpler option for a single-app, single-mailbox setup like this one.

Part 2: Configure the Tool in Wabee Studio

  1. Access the Tool Management Dashboard

    • Log in to your account and navigate to the "Tools" section.
    • Click on the "Catalog" tab to view available tools.

  2. Locate the Microsoft 365 Email Outbox Tool

    • Look for the "Microsoft 365 Email Outbox" card or use the search to locate the tool.
    • Click the "Configure Tool" button to begin the setup process.

  3. Fill in the Configuration Form

    • Tool Name: A name to identify this tool instance within the platform.
    • Description: A description of the tool's purpose. Agents read it to decide when to use the tool, so mention what kind of emails it should send.
    • Microsoft Entra tenant ID: The Directory (tenant) ID copied in Part 1, Step 1.
    • Application (client) ID: The Application (client) ID copied in Part 1, Step 1.
    • Client secret value: The secret Value copied in Part 1, Step 3. The field is masked and the value is stored encrypted.
    • Sender mailbox address: The Microsoft 365 mailbox to send as (this becomes the From address). It must be a real mailbox in your tenant covered by the permissions configured above.
    • Sender display name (optional): The name shown next to the address in recipients' inboxes. Defaults to the sender address.
    • Graph sender ID / UPN (advanced) (optional): Leave empty in most cases. Only needed when the mailbox sign-in name (userPrincipalName) differs from the email address you are sending from — for example an alias or some shared mailbox setups. Enter the mailbox's userPrincipalName or Entra object ID. Note that sending from an alias also requires an Exchange organization setting to keep the alias as the visible From address — see Troubleshooting below.
    • Recipient cooldown (seconds) (optional): Minimum number of seconds between two emails to the same recipient address. While the window is active, sends to that address are refused and the agent is told to wait. Useful to prevent an agent from accidentally mailing the same person repeatedly. Leave blank to disable.
    • Disable Wabee branding (optional): By default, sent emails include a short "Sent by an agent running at wabee.ai" footer. Set to true to suppress it.
    • Dev recipient override (redirect all sends) (optional): Development/testing safety switch — see below. Leave blank in production.

  4. Review and Submit

    • Double-check all the entered information for accuracy.
    • Click the "Create" button at the bottom of the form to save your configuration.

The configured tool will now appear in the "Configured Tools" tab. To make it available to an agent, follow the Tool Addition and Removal Guide.

Testing Safely with the Dev Recipient Override

While validating the configuration, set Dev recipient override to your own email address. Every send is then redirected to that address — the real To/Cc/Bcc are dropped, and the original recipients are noted in the subject line (for example [DEV -> customer@example.com] Original subject). No customer can receive a test email by accident.

A good first test:

  1. Set the dev recipient override to your address and create the tool
  2. Add the tool to a test agent and ask it to send a short email to any address
  3. Confirm the message arrives in your inbox with the expected sender, subject prefix, and body
  4. Edit the tool configuration and clear the override before using it in production

Delivery is asynchronous

The tool reports success when Microsoft accepts the message for delivery. If Exchange Online cannot deliver it afterwards, a non-delivery report (NDR/bounce) is sent to the sender mailbox — check that inbox when a message seems to have disappeared.

Best Practices & Tips

  1. Client secret lifecycle:

    • Client secrets expire. Record the expiration date and rotate the secret ahead of time: create a new secret in Certificates & secrets, update the tool configuration with the new value, then delete the old secret.
    • To revoke the integration entirely, delete the client secret (or the app registration) in Entra. This blocks the issuance of new access tokens, but it does not invalidate a token the tool has already obtained — sending can continue until that token expires, up to roughly 60–90 minutes (the default Microsoft Entra access token lifetime). If you are responding to a suspected credential exposure, treat that window as part of the incident rather than assuming access stopped instantly.

  2. Least privilege:

    • Apply the application access policy from Part 1, Step 4 so the app can only send as the mailboxes you intend.
    • Use a dedicated app registration for Wabee rather than reusing one shared with other integrations, so it can be revoked independently.

  3. Sender mailbox choice:

    • A shared mailbox (for example notifications@yourdomain.com) works well as the sender and does not require its own license in most tenants.
    • Prefer a verified custom domain over a *.onmicrosoft.com address — mail from onmicrosoft.com addresses is increasingly throttled and filtered.

  4. Guardrails:

    • Set a recipient cooldown if the agent operates autonomously, so a loop or a repeated instruction cannot flood a recipient.
    • Keep the tool description specific about the intended use of email, so agents don't reach for it in unrelated situations.

Troubleshooting

  1. "Authentication failed" / invalid client secret (AADSTS7000215):

    • The client secret is wrong or expired. Make sure you pasted the secret Value, not the Secret ID, and that it hasn't passed its expiration date. If in doubt, create a fresh secret and update the tool.

  2. Application or tenant not found (AADSTS700016, AADSTS90002):

    • The tenant ID or client ID is incorrect, or the app registration lives in a different tenant. Re-copy both values from the app registration's Overview page.

  3. Send fails with "Access denied" / authorization error:

    • Admin consent for the Mail.Send application permission is missing — verify the green "Granted" status on the API permissions page (Part 1, Step 2), and that you added the Application permission, not the Delegated one.
    • If an application access policy is configured, verify it includes the sender mailbox using Test-ApplicationAccessPolicy.
    • The tool discards its cached token after an authorization failure, so once the permission is fixed you can simply retry.

  4. Send fails with "user not found" (ErrorInvalidUser / ResourceNotFound):

    • The sender address is not the mailbox's sign-in name. Fill in the Graph sender ID / UPN (advanced) field with the mailbox's userPrincipalName or Entra object ID (find both on the user's page in the Entra admin center).

  5. Recipients see the mailbox's primary address instead of the alias configured as sender:

    • By default, Exchange Online rewrites a From address that is an alias (proxy address) to the mailbox's primary SMTP address during sending. To preserve aliases, an Exchange administrator must enable sending from aliases for the organization: Set-OrganizationConfig -SendFromAliasEnabled $true (this is tenant-wide and can take up to an hour to take effect).

  6. The tool reports success but the email never arrives, and the sender mailbox receives a bounce (NDR) with 550 5.7.708 "Access denied, traffic not accepted from this IP":

    • This is a Microsoft tenant-level restriction, not a tool problem: Exchange Online blocks outbound external email from brand-new or trial tenants and from tenants that send only from *.onmicrosoft.com addresses, until they establish reputation.
    • Verify a custom domain in Microsoft 365 and send from an address on it, make sure the tenant has paid licenses, or test with recipients inside your tenant (internal delivery is not restricted). Established production tenants do not hit this.

  7. The agent is told a recipient is "in cooldown":

    • This is the recipient cooldown guardrail working as configured — the same address was emailed less than the configured number of seconds ago. Wait for the window to pass, or lower/clear the cooldown in the tool configuration.

Conclusion

By following these steps, you have connected a Microsoft 365 mailbox to Wabee using a modern, password-less application identity, and your AI agents can now send emails through it — with encryption of credentials at rest, optional sending guardrails, and a safe way to test before going live.

For additional assistance, please contact our support team, or refer to Microsoft's documentation on app-only access with client credentials and limiting application mailbox access.