Email

Operator runbook for sending email from IdentityMesh. One setting controls every message the product sends: self-service group notifications, the workflow Send email step and vault check-out approvals.

Email is available on every tier. It is off until an administrator switches it on and saves a provider.

Where it lives

Console → Settings → Email tab, in the Integrations group between Integrations and SIEM Integrations. Viewing the tab needs the roles.read permission. Save, Clear and Send test need roles.write.

What sends email

Self-service groups. Requests, decisions, owner changes and expiry notices. See Self-service groups.
Workflows. The Send email step. See Mesh workflows.
Vault check-outs. When a check-out request needs approval, every approver is told, and the requester is told the decision. See Vault operations.

Every notification also appears in the person’s inbox in the console. Email is in addition to the inbox, never instead of it. A person with no email address on their object gets the inbox notification only.

Message bodies are plain text.

Choose a provider

One provider is active at a time. Pick it with the provider selector, fill in its card, tick Send email and save.

Each provider keeps its own saved values. Switching from one provider to another and back does not make you retype anything.

Provider	You need
SMTP	Host, port (default 587), STARTTLS on or off, From address, and optionally a username and password
Mailgun	Sending domain, region (US or EU), From address, API key
Microsoft 365	Tenant ID, application (client) ID, the mailbox to send as, client secret

Secrets

Secret fields (SMTP password, Mailgun API key, Microsoft 365 client secret) show ******** when a secret is stored. The page never shows a stored secret back to you.

Leave the field blank, or leave the mask, to keep the stored secret.
Press Clear beside the field to remove the stored secret.
You cannot clear the secret of the provider that is active while Send email is on. The page answers “Disable email or switch provider first.” Switch email off or choose another provider, then clear it.

No secret ever leaves the server.

What must be filled in

The page checks only the active provider, and only when Send email is on. Missing fields are named under the field.

SMTP: host and From address. A password is needed only when a username is set.
Mailgun: domain, region, From address and the API key.
Microsoft 365: tenant ID, client ID, mailbox and the client secret.

SMTP

Enter the host name of your mail server, the port (587 by default) and whether to use STARTTLS. Enter a username and password if the server requires sign-in. The From address is the sender recipients see.

Mailgun

In Mailgun, add your sending domain and complete its verification. Mailgun will not send for a domain that is not verified.
Note the region the domain was created in. Choose EU in IdentityMesh if it was created in the EU region, otherwise US.
Create a sending key for the domain, or use an account key. Paste it as the API key.
Enter the domain and a From address on that domain.

Microsoft 365

IdentityMesh sends mail as one mailbox through Microsoft Graph, using an app registration in your tenant.

In Microsoft Entra ID, register an application.
Under API permissions, add the application permission Mail.Send for Microsoft Graph, then grant admin consent.
Create a client secret for the application.
In IdentityMesh, enter the tenant ID, the application (client) ID, the client secret and the mailbox to send as, for example notifications@contoso.com.

Restrict which mailboxes the app can send as

By default, Mail.Send lets the application send as any mailbox in the tenant. Limit it to the one mailbox with an Exchange Online application access policy. Create a mail-enabled security group that contains only that mailbox, then run in Exchange Online PowerShell:

New-ApplicationAccessPolicy -AppId <app id> `
    -PolicyScopeGroupId <mail-enabled security group> `
    -AccessRight RestrictAccess `
    -Description "IdentityMesh may send as the notification mailbox only"

Test-ApplicationAccessPolicy -AppId <app id> -Identity notifications@contoso.com

The test should report access granted for the notification mailbox. Run it again with another mailbox: it should report access denied. The policy can take up to an hour to apply.

Messages are sent with Graph sendMail and are not saved to the mailbox’s Sent Items.

Send test

Send test sends a fixed message to an address you enter. It uses the saved settings, not what is typed on the page, so save first. A failure shows the provider’s status and reason. It never shows a credential.

Vault approval notifications

When a vault check-out request needs approval, every member of the account’s approver role gets an inbox notification and an email. The requester gets the decision: approved with the minutes granted, or denied with the reason. Details are in Vault operations.

Troubleshooting

What you see	Cause
SMTP 535, Mailgun 401 or 403, or Microsoft 365 “rejected the app credentials”	The credential is wrong or expired. Enter it again.
Microsoft 365 403 “refused to send as”	Mail.Send was not consented, or the access policy excludes the mailbox.
Microsoft 365 404, mailbox not found	The mailbox address is wrong.
429, a 5xx status, or “could not be reached”	A temporary problem. Workflow steps retry automatically.
“The email secret cannot be read on this host”	The secret was stored on another server. Enter it again and save.
“Email is not configured”	Switch Send email on and save.
“Disable email or switch provider first.”	You tried to clear the secret of the active provider.

Upgrading from the old SMTP relay

If the SMTP relay was configured under Configure → Groups, it keeps sending. Its settings now appear under Settings → Email with SMTP selected. Configure → Groups shows a link to Settings → Email in place of the relay tab.