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 OAuth grant / flow 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. See our Authorization Code Grant setup guide for a detailed walkthrough.
Configuration:
| Field | Description |
|---|---|
| Permission URL | Use the default value or, if necessary, replace common or organizations with your tenant ID (Microsoft 365 only) |
| Token URL | Like the permission URL, this can be edited if needed 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., Entra / Azure for public clients and certain flows) |
| 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 if needed 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., Entra / Azure for public clients and certain flows) |
Use cases: When users can’t visit Auth-Email directly, or want a simpler login flow. Users enter a code on a separate device or browser 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. As a result, this flow requires administrator consent to grant the necessary permissions. See our Microsoft 365 Client Credentials Grant setup guide for help configuring this flow with Entra / Azure / Office 365.
Configuration:
| Field | Description |
|---|---|
| Token URL | Use the default value |
| 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 always 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, but available on Microsoft 365 accounts if needed. See our Resource Owner Password Credentials grant setup guide.
Configuration:
| Field | Description |
|---|---|
| Token URL | Use the default value or, if necessary, replace common or organizations 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., Entra / Azure 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.
5. Service Account
Not a separate OAuth flow as such, but a method for authenticating Google Workspace accounts without requiring interactive authorization from users. Similar to the Client Credentials Grant, this method uses a non-user service account with domain-wide delegation.
Configuration:
| Field | Description |
|---|---|
| Token URL | Use the default value |
| OAuth scope | Use the default value |
| Service account key | Enter your service account key, which is provided when setting up the service account |
Use cases: As with the Client Credentials Grant, this option provides broad access across mailboxes without the need for users to grant permission.
💡 Need help?
If you’re unsure which OAuth flow to use or what configuration is required for your provider, email us at [email protected] and we’ll be happy to help get you going.