Use Microsoft 365 to send and receive emails in Mojo

If you have a Microsoft 365 mailbox (e.g. support@newco.com), Mojo Helpdesk can retrieve emails from this mailbox and create tickets. It will also use Microsoft 365 to send emails to ticket creators and agents. This is a step-by-step guide on how to configure Mojo and Microsoft 365. Mojo uses OAuth2 for secure authentication - no passwords are stored. It leverages IMAP for receiving emails and SMTP for sending emails.

Prerequisites

  1. A Microsoft 365 account (Business Basic, Business Standard, or Enterprise)
  2. Admin access to the Microsoft 365 tenant (or permission to consent to third-party apps). You will also need the sign-in credentials for the mailbox account itself (e.g. support@newco.com) — not just the admin account.
  3. "Authenticated SMTP" enabled for the mailbox (see Step 1)

Instructions

Step 1: Enable Authenticated SMTP in Microsoft 365 Admin Center

Microsoft disables Authenticated SMTP by default. It must be enabled for the mailbox you plan to use.

  1. Sign in to the Microsoft 365 admin center: https://admin.microsoft.com
  2. Go to Users > Active users.
  3. Select the user whose mailbox you want to use (e.g. support@newco.com).
  4. Click the Mail tab.
  5. Under Email apps, click Manage email apps.
  6. Check the box for Authenticated SMTP.
  7. Click Save changes.

Note: This change may take a few minutes to take effect.

Step 2: Configure the mail server in Mojo Helpdesk

  1. Navigate to your help desk Admin > Channels > Email > Server configuration.
  2. Click on use my own mail server and follow the step-by-step guide.
  3. For receiving emails (email-to-ticket creation), enter the following details:
    IMAP server address: outlook.office365.com
    Username: Your Microsoft 365 email address (e.g. support@newco.com)
    Port: 993 (SSL enabled)
  4. For outgoing mail settings (outbox configuration), enter the following:
    SMTP server: smtp.outlook.com
    Port: 587 (TLS enabled)

When a Microsoft 365 IMAP server is detected, Mojo automatically hides the password fields and other settings that are not needed - authentication is handled securely through OAuth2 in the next step.

Step 3: Connect with Microsoft 365

  1. Click the Connect with Microsoft 365 button. You will be redirected to Microsoft's sign-in page.
  2. Important: Sign in with the Microsoft 365 account that owns the mailbox (e.g. support@newco.com), not your personal admin account. The sign-in page will be pre-filled with the mailbox email address to help you select the correct account.
  3. Review the permissions requested and click Accept.
  4. You will be redirected back to Mojo Helpdesk. The system will automatically attempt to send a test email to verify the setup.
  5. If the connection is successful, you will see a confirmation message and the mail server status will show "Server is sending emails successfully".

If the mailbox account cannot grant consent: Some Microsoft 365 tenants require admin consent for third-party apps. If the mailbox user sees a "Need admin approval" message, the setup requires two steps:

  1. First, have a Microsoft 365 admin click "Connect with Microsoft 365" and sign in with their admin account to grant consent for the organization. Mojo will show a warning that the signed-in account doesn't match the mailbox — this is expected.
  2. Then, click "Connect with Microsoft 365" again (a button will appear in the warning banner) and this time sign in as the mailbox account (e.g. support@newco.com). Since consent was already granted by the admin, no additional approval will be needed.

Tip: Use a private/incognito browser window when connecting to avoid being automatically signed in with the wrong Microsoft account.

Step 4: Verify the setup

After connecting, check the Server configuration page:

  • Sending status: Should display "Server is sending emails successfully" with the date of the last sent email.
  • Receiving status: Should display "Server is receiving emails successfully" after the first email is fetched (this may take a few minutes).
  • OAuth2 badge: A "Microsoft 365 OAuth2" badge will appear next to the server information, confirming that OAuth2 authentication is active.

If the test email fails (e.g. due to "Authenticated SMTP" not being enabled), you will see an error message. Fix the underlying issue and click Send test email from the dropdown menu to retry.

Step 5: Configure DKIM, SPF, and DMARC for Your Domain

To ensure reliable email delivery and protect your domain from spoofing or unauthorized use, it's critical to configure DKIM, SPF, and DMARC records. These settings help authenticate emails sent from your domain and prevent them from being flagged as spam. For Microsoft 365, ensure your DNS records include:

  • SPF: Add Microsoft's servers to your SPF record (e.g. include:spf.protection.outlook.com).
  • DKIM: Enable DKIM signing in the Microsoft 365 Defender portal under Email authentication settings.
  • DMARC: Configure a DMARC policy for your domain to monitor and enforce email authentication.

This step is essential for maintaining the integrity and deliverability of your emails when using Mojo Helpdesk with Microsoft 365.

How it works

Unlike traditional username/password authentication, Mojo Helpdesk uses OAuth2 to connect to Microsoft 365. This means:

  • No passwords are stored - Mojo uses secure access tokens granted by Microsoft.
  • Tokens are refreshed automatically - Mojo periodically refreshes the access token before it expires, so the connection remains active without any manual intervention.
  • Reconnect at any time - If the OAuth2 connection breaks (e.g., due to a password change or revoked consent), use the Reconnect with Microsoft 365 option in the dropdown menu to re-authorize.

Removing or changing the mail server

  • Change to Mojo Helpdesk email service (SaaS accounts): This switches your account back to using Mojo's built-in email service. Your Microsoft 365 settings are preserved in case you want to switch back later. Any active sending/receiving warnings are automatically cleared.
  • Erase settings: This permanently deletes your mail server configuration, including all OAuth2 tokens and credentials. The account reverts to Mojo's built-in email service. Use this if you want a clean start or want to configure a completely different mail server.

In both cases, Mojo stops using Microsoft 365 for sending and receiving emails immediately.

Troubleshooting

"Authenticated SMTP" error or timeout when sending emails

  • Verify that Authenticated SMTP is enabled for the mailbox in the Microsoft 365 admin center (see Step 1). This is the most common cause of sending failures.
  • The change may take a few minutes to propagate after enabling.
  • If Authenticated SMTP is enabled but you still get a timeout, check these additional Microsoft 365 settings:


    • Security Defaults: If enabled in Azure AD (Entra ID), it blocks SMTP AUTH. Check at: entra.microsoft.com > Identity > Overview > Properties > Manage security defaults.

    • Organization-level SMTP AUTH: Even if enabled per-mailbox, the org-wide setting may override it. Check in Exchange Admin Center under Settings > Mail flow.

    • Conditional Access policies: Policies blocking "Other clients" or legacy authentication may interfere. Add the mailbox as an exclusion if needed.

  • After making changes in Microsoft 365, wait 15-30 minutes for them to propagate, then click Reconnect with Microsoft 365.

"You signed in as '...' but the mailbox is configured for '...'" error

This means you signed into Microsoft with a different account than the mailbox configured in Mojo. This commonly happens when an admin signs in to grant consent instead of the mailbox user.

To fix this:

  1. Click the Connect with Microsoft 365 button shown in the warning banner on the configuration page.
  2. When redirected to Microsoft's sign-in page, sign in with the mailbox account (e.g. support@newco.com). If an admin previously signed in to grant consent, that step is already complete and won't be required again.
  3. Use a private/incognito browser window if your browser keeps auto-signing in with the wrong account.

"Send As Denied" error

  • The "From" address used when sending emails must match the mailbox email address. Mojo automatically sets the "From" address to match the IMAP username when OAuth2 is active.
  • If you still see this error, check your Microsoft 365 "Send As" permissions in the Exchange admin center.

Token refresh failure / "Failed to receive emails" warning

  • If the OAuth2 token cannot be refreshed, a warning banner will appear in your helpdesk. This can happen if:
  • The Microsoft 365 admin revoked consent for the app.
  • The user's password was changed or the account was disabled.
  • To fix this, go to Admin > Channels > Email > Server configuration, and use Reconnect with Microsoft 365 from the dropdown menu (⋮) to re-authorize.

Test email sent but not received

  • After connecting, click Send test email from the dropdown menu to send a new test email.
  • Check that the mailbox's inbox is not full and that there are no mail flow rules blocking the test email.

General tips

  • Ensure the mailbox is a regular user mailbox (not a shared mailbox without a license).
  • Check for any Conditional Access policies in Azure AD that might block IMAP or SMTP access for the app.
  • Review the server status on the Server configuration page for detailed error messages.