Creating custom OAuth configurations
Auth-Email supports using custom OAuth clients for secure, provider-authorized access to email accounts — perfect for organizations managing their own credentials or using internal authentication procedures.
This guide walks through the process of adding a custom OAuth client in your Auth-Email dashboard and explains each supported OAuth flow in detail.
This feature requires a subscription to Auth-Email's Pro plan.
When to use a custom OAuth client
You might use a custom OAuth client when:
- Your organization manages its own Microsoft 365, Google Workspace, or other email infrastructure
- You require strict control over scopes, tokens, and consent
- You're using OAuth flows that need specific redirect URIs or advanced grant types
Step-by-step: adding a custom client
- Log in to the Auth-Email dashboard, then click “Settings” in the top menu
- Click “Add client”
- Enter a name to identify this client when configuring an email account later
- Select the mail provider you will use this custom client for (e.g. Microsoft, Google, 21Vianet, etc.)
- The rest of the form updates to show configuration fields based on the provider's supported OAuth grant / flow types
- Continue reading the rest of this page to understand how to configure your choice of flow
OAuth flows explained
Each provider supports a different set of OAuth flows. The rest of this page describes the supported flows and use-cases, and how to configure each one.
The client configuration form will change based on the flow you select, so make sure to choose the right one for your use-case. Where possible, the form will pre-fill default values based on the provider's documentation.
1. Authorization Code Grant
The most common flow for user-authenticated access. This method authorizes access by redirecting the user to a login page and returns to Auth-Email with an authorization code, which is automatically exchanged for short-lived access tokens.
Configuration:
| Field | Description |
|---|---|
| Permission URL | Use the default value or, if necessary, replace common with your tenant ID (Microsoft 365 only) |
| Token URL | Like the permission URL, this can be edited to add in your tenant ID in place of the default |
| OAuth scope | Defines what access your app is requesting. The default is to request all protocols (IMAP/POP/SMTP). If editing this value, be sure to separate scopes using spaces |
| Client ID | Your app's Client ID. This is set by your mail provider |
| Client secret | Optional. Only required if your provider uses a client secret. Required by some providers (e.g., Azure AD / Entra for public clients) |
| PKCE | Enable if your provider requires the use of Proof Key for Code Exchange |
| Redirect URI | URI to redirect to when receiving the authorization response from your provider. You can use: |
|
Use cases: Interactive user consent, with a redirection to the provider's login page from the Auth-Email dashboard. This is the most widely supported flow.
2. Device Authorization Grant
This flow is an alternative to the authorization code flow, originally intended for non-browser environments. When using Auth-Email, this method can be used as an alternative if you are required to use a specific device to log in to your account, but cannot access the Auth-Email dashboard in that context.
Configuration:
| Field | Description |
|---|---|
| Permission URL | Use the default value or, if necessary, replace common with your tenant ID (Microsoft 365 only) |
| Token URL | Like the permission URL, this can be edited to add in your tenant ID in place of the default |
| OAuth scope | Defines what access your app is requesting. The default is to request all protocols (IMAP/POP/SMTP). If editing this value, be sure to separate scopes using spaces |
| Client ID | Your app's Client ID. This is set by your mail provider |
| Client secret | Optional. Only required if your provider uses a client secret. Required by some providers (e.g., Azure AD / Entra for public clients) |
Use cases: When users can’t visit Auth-Email directly, or want a simpler login flow. Users enter a code on a separate device to authenticate.
3. Client Credentials Grant
This is a non-interactive flow typically used for system-to-system access (e.g., a backend service connecting to an API). When used with email accounts, it allows IMAP/POP/SMTP access to an account without user interaction or explicit consent.
Configuration:
| Field | Description |
|---|---|
| Token URL | Use the default value or, if necessary, replace common with your tenant ID (Microsoft 365 only) |
| OAuth scope | Defines what access your app is requesting. The default is to request all protocols (IMAP/POP/SMTP). If editing this value, be sure to separate scopes using spaces |
| Client ID | Your app's Client ID. This is set by your mail provider |
| Client secret | Your app's Client secret. This is set by your mail provider. Unlike other flows, the Client Credentials Grant requires a Client Secret value. |
Use cases: Broad access across mailboxes without the need for users to authorize individual accounts. Note that this flow requires an administrator to grant access permissions.
4. Resource Owner Password Credentials Grant
This flow allows apps to obtain tokens by directly using the real username and password of the user. Considered legacy and less secure.
Configuration:
| Field | Description |
|---|---|
| Token URL | Use the default value or, if necessary, replace common with your tenant ID (Microsoft 365 only) |
| OAuth scope | Defines what access your app is requesting. The default is to request all protocols (IMAP/POP/SMTP). If editing this value, be sure to separate scopes using spaces |
| Client ID | Your app's Client ID. This is set by your mail provider |
| Client secret | Optional. Only required if your provider uses a client secret. Required by some providers (e.g., Azure AD / Entra for public clients) |
Use cases: Only when absolutely necessary, typically in controlled environments. Discouraged by most providers due to the need for direct login with the user's real password. .
Need help?
If you’re unsure which OAuth flow to use or what configuration is required for your provider, email us at support@auth-email.com and we'll be happy to help get you going.