What is this about?
By default, unixpass sends system e-mails (invitations, registration codes, notifications) through the central unixpass mail server. With the user-defined e-mail transport, your installation sends directly through your own Microsoft 365 tenant via the Microsoft Graph API. Benefits: e-mails originate from your own domain, are SPF/DKIM/DMARC compliant and are far less likely to end up in spam.
Who configures what?
Own unixpass installation (OnPremise / Master)
You configure everything yourself in UXP-Admin (part 2 of this howto).
Tenant on the R3levance cloud
You only complete part 1 (Microsoft Entra) and securely hand the three values to R3levance support — they will set up the transport for your tenant.
Prerequisites
- Microsoft 365 tenant with access to the Entra admin center (role: Global Administrator or Application Administrator)
- An app registration for unixpass (“UXP”) — the same app can be used for SSO (login via O365) and for mail sending
- An existing mailbox (or shared mailbox) in the tenant used as the sender address, e.g.
noreply@your-domain.com
Part 1 — Microsoft Entra: authorize the app
Open the app registration
Sign in to the Entra admin center and open Entra ID → App registrations. Select the existing UXP app. If none exists yet: New registration → name “UXP”, account type “Accounts in this organizational directory only”.
Add the Mail.Send permission
In the UXP app, open API permissions and click Add a permission → Microsoft Graph → Application permissions. Search for Mail.Send (“Send mail as any user”) and add it. Important: the type must be Application, not “Delegated” — unixpass sends without a signed-in user.
Grant admin consent
Application permissions require administrator consent. Click Grant admin consent for <your organization> and confirm. The Status column then shows a green “Granted” check mark.
Create a client secret
Open Certificates & secrets → New client secret. Enter a description (e.g. “unixpass mail sending”) and an expiry period. Copy the value immediately — it is shown only once.
Recommended: restrict sending to the sender mailbox
Mail.Send as an application permission technically allows the app to send as any user of the tenant. Use an application access policy in Exchange Online to restrict the app to the single sender mailbox:
# Exchange Online PowerShell (Connect-ExchangeOnline)
New-DistributionGroup -Name "UXP-MailSend-Allowed" -Type Security
Add-DistributionGroupMember -Identity "UXP-MailSend-Allowed" -Member noreply@your-domain.com
New-ApplicationAccessPolicy -AppId <APPLICATION-ID> -PolicyScopeGroupId UXP-MailSend-Allowed@your-domain.com -AccessRight RestrictAccess -Description "UXP may only send as noreply"
# Verify:
Test-ApplicationAccessPolicy -Identity noreply@your-domain.com -AppId <APPLICATION-ID>You now have these three values
| Application (client) ID | CLIENT_APP_ID — GUID from the app overview |
|---|---|
| Client secret | CLIENT_APP_SECRET — the value copied in step 4 |
| Directory (tenant) ID | TENANT_ID — GUID from the app overview |
Part 2 — unixpass: configure the e-mail transport
In UXP-Admin, open the tenant settings and enable the User-defined e-mail transport section:
Anatomy of the DSN
microsoftgraph+api:// | transport scheme: sending via the Microsoft Graph API |
CLIENT_APP_ID | application (client) ID of the UXP app |
CLIENT_APP_SECRET | client secret (value). If the secret contains special characters such as / @ : ?, they must be URL-encoded (e.g. / → %2F) |
@default | fixed part |
?tenantId=TENANT_ID | directory (tenant) ID of the M365 tenant |
Testing & troubleshooting
Trigger a system e-mail (e.g. an invitation or a registration code) and check delivery. Typical issues:
| Mail not delivered, error “insufficient privileges” | Admin consent for Mail.Send missing (part 1, step 3), or the permission is “Delegated” instead of “Application”. |
| Error “invalid client secret” / 401 | Secret copied incorrectly, expired, or special characters not URL-encoded. |
| Error “ErrorAccessDenied” | An application access policy blocks the sender mailbox — check group/policy (Test-ApplicationAccessPolicy). |
| Sender rejected / NDR | Sender e-mail does not belong to a mailbox in the tenant. |
| Sending suddenly stops after months | Client secret expired — create a new secret and update the DSN. |