Before you begin
- The Administrator role in Atlas AVD
- For Microsoft Graph: an app registration in your Microsoft Entra directory, its client secret, and a Global Administrator or Privileged Role Administrator who can grant admin consent
- For Microsoft Graph: a licensed (or shared) Exchange Online mailbox to send from, in the same Entra tenant as the app registration
- For SMTP: your mail server's host name, port, and a username and password
Open Email Settings
In the sidebar, expand Settings and click Email Settings. If no tenant is selected you are asked to pick one from the top navigation first, because each tenant has its own email configuration.
The strip at the top of the page shows the current state at a glance: Email Configuration (the provider in use, with a Connected or Needs attention badge), Sender (the address mail is sent from), Last sent (the most recent successful delivery) and Recent Failures (failed sends among the last ten attempts). Check re-reads the saved configuration and re-runs the permission check without sending anything, and Full Audit Log opens every delivery attempt.
Choose a provider
Under Sender Config, pick Microsoft Graph or SMTP. Microsoft Graph is selected by default for a tenant that has never been saved. Switching provider is shown as Unsaved changes and takes effect only when you click Save. Saving with SMTP selected removes the stored Graph client secret from the configuration, so switch back only when you are ready to enter it again.
Microsoft Graph: register the app
Atlas sends with the Microsoft Graph sendMail API as an application, so it needs an app registration with the Mail.Send application permission. If Atlas was set up with the Atlas app registration on your primary tenant, the Azure Tenant ID and App (Client) ID are filled in for you (Auto-filled from your saved Azure configuration — click Save to apply) and you can skip to the client secret. Otherwise, create one in the Microsoft Entra admin center:
- Go to Identity → Applications → App registrations and click New registration. Give it a name such as Atlas AVD Email, keep Single tenant, and click Register.
- On the app's Overview page, copy the Directory (tenant) ID and the Application (client) ID.
- Open API permissions → Add a permission → Microsoft Graph → Application permissions, search for Mail.Send, select it and click Add permissions. It must be an Application permission, not Delegated.
- Open Certificates & secrets → New client secret, add a description and expiry, and copy the secret's Value straight away (it is shown only once).
The app registration and the sender mailbox must be in the same Microsoft Entra tenant. An application Mail.Send permission can only send as mailboxes in its own tenant, so a sender in another tenant fails every send.
Microsoft Graph: enter the details and save
- Azure Tenant ID: paste the Directory (tenant) ID. The field shows Valid once it is a well-formed GUID.
- App (Client) ID: paste the Application (client) ID.
- Client Secret: paste the secret value. If the badge says Optional, Atlas already holds the secret for this app registration; leave it blank to reuse it, or paste a different one to override it.
- Sender Email: the mailbox Atlas sends as, for example avd-alerts@yourdomain.com.
- Click Save. You should see Settings saved.
The client secret is stored only in Azure Key Vault, never in the database. Once stored, the field shows Stored in Key Vault; use Rotate secret to replace it before it expires. Leaving the field blank on a later save keeps the current secret.
Microsoft Graph: grant Mail.Send admin consent
The Setup Progress card tracks four steps: App registered, Secret stored, Mail.Send permission and Email delivered successfully. Steps still to do are highlighted. Once the secret is stored, Atlas checks the permission live by requesting a token for the app and looking for Mail.Send in it; no email is sent.
If the Permissions section shows Mail.Send — Requires attention, click Grant Consent (or Grant on the checklist). It opens Microsoft's admin consent page in a new tab for your tenant; sign in as an administrator who can grant consent and accept. Back in Atlas, click the Re-check permission icon or Check. When consent is in place the section shows Mail.Send, Application permission and Admin consent with green ticks.
Consent can take a few minutes to reach Microsoft Graph. If the check still reports Admin consent not yet granted right after you accepted, wait a moment and re-check. You can also grant it from the app registration's API permissions page with Grant admin consent for your organization.
SMTP: enter your mail server
Select SMTP under Sender Config and fill in:
- SMTP Host: your mail server, for example smtp.office365.com for Exchange Online or your relay's host name.
- Port: 587 by default (STARTTLS). Turn on Use TLS / Implicit SSL (port 465) if your server uses implicit TLS on port 465.
- Username and Password: the account that signs in to the server. The password is stored in Azure Key Vault and can be replaced later with Rotate secret.
- Sender Email: the From address. Your server must allow the username to send as it.
Atlas always encrypts SMTP connections with TLS 1.2 or later and checks the server's certificate, so unencrypted port 25 is not accepted. Sign-in is username and password; if you use Exchange Online, SMTP AUTH must be enabled for the sending mailbox, otherwise Microsoft Graph is the simpler choice.
Send a test email
In the Send Test Email card, enter a Recipient Address and click Send Test. If you have unsaved changes, Atlas saves them first. A successful test shows Delivered successfully with the recipient, the provider used and how long it took, and completes the last step of Setup Progress. A failure shows the reason under the card.
Recent Email Activity lists the last five deliveries with the subject, recipient, provider and time, and refreshes on its own. View all and Full Audit Log open the Email Audit Log, where you can search by recipient, subject or error, filter by Success or Failed and by date, and export to CSV or Excel.
Advanced
Expand Advanced at the bottom of the page to see the permissions a Graph app registration needs, the names of the Key Vault secrets holding your client secret or SMTP password, and the raw response of the last permission check, which is useful when you raise a support ticket.
GCC High
On a GCC High tenant, Atlas sends through the US Government Microsoft Graph endpoints and the Grant Consent button opens the Government sign-in page, so you configure Graph exactly as above, in your Government Entra directory. If you use SMTP, enter your Government mail host yourself.
Troubleshooting
- Admin consent not yet granted: click Grant Consent, accept as an administrator, wait a few minutes, then re-check. Make sure Mail.Send was added as an Application permission.
- Auth failed: check credentials: the client ID or client secret is wrong, or the secret has expired. Create a new secret in Entra and use Rotate secret.
- Sender tenant mismatch: the sender's domain belongs to a different Entra tenant than the app registration. Use a mailbox in the app's tenant, or register the app in the tenant that owns the domain and use that tenant's ID.
- Mailbox not found: the sender address isn't a mailbox in the tenant. Check for typos and use a licensed or shared Exchange Online mailbox, not a guest or unlicensed account.
- Access denied sending mail: the app lacks Mail.Send consent, or an Exchange policy blocks the app from sending as that mailbox.
- SMTP sign-in errors: check the username, password, port and TLS setting, and that your server allows authenticated SMTP for that account.