OAuth Email Tool

The OAuth Email Tool sends emails as part of workflow processes using OAuth 2.0 authentication instead of a stored SMTP password.

Two OAuth delivery methods are supported: SMTP with the XOAUTH2 SASL mechanism, and the Microsoft Graph API. Graph mode sends without any SMTP configuration at all, which suits organisations where SMTP submission is blocked or SMTP AUTH is disabled.

The tool is a drop-in alternative to the standard Email Tool. It supports the same message, recipient, and attachment options, and adds an authentication mode selector plus an OAuth 2.0 configuration section.

Plugin Information

Plugins Available in the Bundle:

• OAuth Email Tool

License: Apache License, Version 2.0

This plugin bundle is compatible with Joget DX 8 and Joget DX 9.

Get Started

Prerequisites

• Joget DX 8 Enterprise or Community Edition.
• Developer or administrator access with permissions to manage plugins.

Where to get the plugin

You can obtain the plugin JAR file by downloading the latest release from the Joget Marketplace.

How to install

1. Download the latest release .jar file from the repository releases page.
2. Log in to your Joget Console.
3. Navigate to the Admin Bar and select Settings > Manage Plugins.
4. Click the Upload Plugins button, select the downloaded JAR file, and click Upload.

Relationship to the Email Tool

All shared configuration behaves exactly as documented for the standard Email Tool. Refer to that article for:

Prerequisites

Before configuring the tool, you need OAuth client credentials from your mail provider. Follow the section matching your provider.

Gmail / Google Workspace

You need a Google account and access to the Google Cloud Console. No billing account or paid plan is required. OAuth and the Gmail scope are available on the free tier.

If the sending address belongs to a Google Workspace organisation, note that administrators can restrict which third-party applications users are permitted to authorize. If authorization is blocked with an administrative policy message, ask your Workspace administrator to allow the app, or use a personal Gmail account for testing.

Step 1: Create a project

Open the Google Cloud Console and create a new project, or select an existing one. Note the project name shown in the selector at the top of the page so you can return to it later.

Step 2: Configure the consent screen

Navigate to Google Auth Platform. This section was previously called APIs & Services > OAuth consent screen, and the single setup wizard has been split across four pages in the left navigation.

Branding

Complete these three fields and save:

• App name: any label, e.g. Joget OAuth Email
• User support email
• Developer contact email

Leave Application home page, Application privacy policy link, Application terms of service link, and Authorized domains empty. These are only enforced when an application is submitted for verification. Entering a home page URL without also registering its domain under Authorized domains will cause the save to fail.

Audience
Navigate to Audience.

1. User type should be External. If your project belongs to a Workspace organisation, an option to switch to Internal is offered. Internal is preferable when the sending address is in the same organisation, because it removes both the unverified-app warning and the seven-day refresh token expiry described in Step 5. Do not choose Internal if the sending address is a personal Gmail account.
2. Publishing status should remain Testing.
3. Under Test users, click Add users and enter the address that will send mail. Only listed test users can authorize the application. Test users are saved as soon as the dialog is confirmed.

Recipients do not need to be listed as test users. Only the sending account does.

Data Access

Navigate to the Data Access Page.

1. Click Add or remove scopes
2. Scroll to the bottom of the panel to Manually add scopes the scope you need does not appear in the filtered list above
3. Paste https://mail.google.com/ exactly, including the trailing slash
4. Add to table > Update > Save.

The scope is categorised as Restricted. This is expected and does not prevent use while the app is in Testing status.

Step 3: Enable the Gmail API

From the main navigation menu, go to APIs & Services > Library, search for Gmail API, and click Enable.

Step 4: Create the OAuth client

1. Return to Google Auth Platform > Clients > Create client.
   
   
2. Application type: Web application (and not Desktop app; desktop clients cannot use the redirect URI below).
   
3. Give the client a name.
   
4. Under Authorized redirect URIs, click Add URI and enter exactly:

    https://developers.google.com/oauthplayground

   
   
   
   Note
   Do not add a trailing slash. Google matches this value character for character, and a mismatch produces redirect_uri_mismatch
5. Create, then copy the Client ID and Client secret.
   

   Step 5: Obtain a refresh token

   1. Open the OAuth 2.0 Playground.
      
   2. Click the gear icon in the top right and tick Use your own OAuth credentials, then paste the Client ID and Client secret that was created in Step 4.
      
   3. In the scope box on the left, type https://mail.google.com/ and click Authorize APIs.
      
      
   4. Sign in as the sending account. Because the application is unverified, a warning appears. Choose Advanced, then go to (app name), and grant consent.
      
   5. On Step 2, click Exchange authorization code for tokens.
      
      
   6. Copy the Refresh token; it begins with 1//. Click into the field and select all, as the input truncates the displayed value.
      

   The Playground's note about revoking refresh tokens after 24 hours does not apply when you supply your own credentials through the configuration panel.

   Note
   While the application remains in Testing publishing status, Google refresh tokens expire after seven days. When this happens the tool reports invalid_grant and a new refresh token must be obtained by repeating this step. Switching the audience to Internal (Workspace organisations only) or completing verification removes this limit. 
   At this point you have everything the tool needs: a Client ID, a Client secret, and a Refresh token.

   Microsoft 365

   Microsoft 365 can be used in either of two modes. Choose before you begin, because the Azure application permission differs.

   Note: Choose SMTP with XOAUTH2 if your tenant permits SMTP AUTH and SMTP.Send can be granted. Choose Microsoft Graph API if SMTP submission is blocked, SMTP AUTH is disabled tenant-wide, or only Mail.Send is available.

   The Steps 1, 2, 4, and 5 mentioned below are identical for both modes. Only the API permission (Step 3) and the requested scope (Step 6) differ.

   Microsoft 365 (SMTP with XOAUTH2)

   Microsoft 365 supports SMTP authentication using OAuth 2.0 and the XOAUTH2 SASL mechanism. This walkthrough uses the Authorization Code / Refresh Token flow, where mail is sent as a specific Microsoft 365 user who has granted consent.

   For a simple test, use a Microsoft 365 organisational account as the sender and any valid email address as the recipient.

   Microsoft 365 authenticated SMTP submission normally uses smtp.office365.com on port 587 with STARTTLS.

   Step 1: Register an application

   Open the Microsoft Entra admin center: 

   Navigate to Entra ID > App registrations > New registration.

   

   Enter: Name

   Example: Joget OAuth SMTP Test

   Supported account types

   For an application that will only use accounts from the same Microsoft 365 organisation, select:

   Single tenant only

   Leave Redirect URI empty for now.

   Click Register.

   

   Step 2: Record the Client ID and Tenant ID

   After registration, Microsoft opens the application's Overview page.

   Record:

   • Application (client) ID
   • Directory (tenant) ID

   

   These correspond to:

   Microsoft Entra	OAuth Email Tool
   Application (client) ID	Client ID
   Directory (tenant) ID	Tenant ID

   Step 3: Add the SMTP.Send permission

   Navigate to API permissions > Add a permission 

   Choose: Microsoft Graph

   

   Then select Delegated permissions, Search for: SMTP.Send

   Select:

   SMTP.Send Send emails from mailboxes using SMTP AUTH

   Click Add permissions.

   

   Note
   In the current Microsoft Entra permission catalog, SMTP.Send is exposed as a Microsoft Graph delegated permission and allows the application to send from the signed-in user's mailbox using SMTP AUTH.

   Step 4: Create a Client Secret

   Navigate to: Certificates & secrets > Client secrets > New client secret. Enter a description such as: Joget OAuth Test.

   

   Microsoft displays:

   • Value
   • Secret ID

   Copy the Value.

   

   The mapping is: Value → OAuth Email Tool Client Secret

   Note
   Do not use the Secret ID.

   Step 5: Configure the Redirect URI

   Navigate to: Authentication > Add a platform

   Choose: Web > Enter http://localhost

   Click Configure.

   

   Leave the following disabled:

   • Access tokens under Implicit grant
   • ID tokens under Implicit grant
   • Allow public client flows
     
     

   Step 6: Obtain an Authorization Code

   Microsoft's authorization endpoint is:

   https://login.microsoftonline.com/{TENANT_ID}/oauth2/v2.0/authorize

   For this test, construct the following URL:

   https://login.microsoftonline.com/{TENANT_ID}/oauth2/v2.0/authorize?client_id={CLIENT_ID}&response_type=code&redirect_uri=http%3A%2F%2Flocalhost&response_mode=query&scope=https%3A%2F%2Foutlook.office.com%2FSMTP.Send%20offline_access&prompt=consent

   Replace {TENANT_ID} with the Directory (tenant) ID from Step 2.

   Replace {CLIENT_ID} with the Application (client) ID from Step 2.

   Open the completed URL in a browser.

   

   Sign in using the Microsoft 365 account that will send email from Joget.

   Accept the requested permission when Microsoft displays the consent screen.

   

   Microsoft documents the SMTP AUTH delegated scope as:

   https://outlook.office.com/SMTP.Send

   The additional offline_access scope allows Microsoft to issue a refresh token that can later be used to obtain new access tokens.

   After authentication, Microsoft redirects the browser to something similar to:

   http://localhost/?code=...&session_state=...

   

   Because no application is actually listening on localhost, the browser may display:

   This site can't be reached or Connection refused

   This is expected for this manual test. The authorization was successful if the browser address bar contains:

   ?code=

   Copy only the value between:

   code= and: &session_state=

   That value is the Authorization Code.

   Example:
   

   Microsoft 365 (Microsoft Graph API)

   This mode posts the message to the Microsoft Graph sendMail endpoint over HTTPS. No SMTP connection is made, no SMTP host or port is configured.

   Both OAuth flows are supported:

   Flow	Permission type	Sends as
   Authorization Code / Refresh Token	Delegated Mail.Send	the signed-in user who consented
   Client Credentials	Application Mail.Send	any licensed mailbox in the tenant

   Application permission is intended for a dedicated shared sending mailbox with no user interaction.

   Step 1, 2, 4, and 5 — identical to the SMTP with XOAUTH2 walkthrough above. Register the application, record the Client ID and Tenant ID, create a client secret, and configure the Redirect URI. The Redirect URI is only needed for the delegated flow.

   Step 3: Add the Mail.Send permission

   Navigate to API permissions > Add a permission > Microsoft Graph, then choose the permission type matching your flow:

   • Delegated permissions — search for and select Mail.Send
   • Application permissions — search for and select Mail.Send
     
     

   Click Add permissions, then Grant admin consent. Application permissions do not take effect until consent is granted; the Status column should show a green tick.

   

   Step 6: Obtain an authorization code (delegated flow only)

   Construct the same URL as the SMTP walkthrough, changing only the scope:

   https://login.microsoftonline.com/{TENANT_ID}/oauth2/v2.0/authorize?client_id={CLIENT_ID}&response_type=code&redirect_uri=http%3A%2F%2Flocalhost&response_mode=query&scope=https%3A%2F%2Fgraph.microsoft.com%2FMail.Send%20offline_access&prompt=consent

   Copy the authorization code from the address bar as described above.

   For the Client Credentials flow, no authorization code is required — skip this step.

   Configure the OAuth Email Tool

   Drag a Tool element onto the Process Builder, click it, select Mapping, and choose OAuth Email Tool from the Tools list.
   

   Complete the Email Message and Attachments sections as described in the Email Tool article, then configure the sections below.

   Gmail / Google Workspace

   Email Settings

   

   Field	Value for Gmail
   From Email Address	The sending Gmail address
   SMTP Host	smtp.gmail.com
   SMTP Port	587
   Security	TLS / STARTTLS
   SMTP Username	The same sending address
   Authentication	OAuth 2.0 (XOAUTH2)

   From Email Address must match SMTP Username. Gmail rewrites a From header that does not correspond to the authenticated account rather than rejecting the message, so a mismatch produces a delivered email with an unexpected sender rather than an error.

   Unlike the standard Email Tool, these fields are required; the tool does not fall back to the SMTP configuration in General Settings.

   OAuth 2.0 Settings

   

   Field	Value for Gmail
   Client ID	from Step 4
   Client Secret	from Step 4
   Tenant ID	leave empty
   Authorization URL	https://accounts.google.com/o/oauth2/v2/auth
   Token URL	https://oauth2.googleapis.com/token
   Scopes	https://mail.google.com/
   Initial Grant Type	Authorization Code / Refresh Token
   Redirect URI	https://developers.google.com/oauthplayground
   Authorization Code	leave empty
   Initial Refresh Token	from Step 5

   Tenant ID is left empty because Google's token URL contains no {tenant} placeholder.

   Google does not support application-only SMTP access, so the Client Credentials grant type cannot be used with Gmail.

   Microsoft 365 (SMTP with XOAUTH2)

   The Client ID, Client Secret, Tenant ID, and Authorization Code referenced below are obtained from the Microsoft 365 prerequisite steps above.

   Email Settings

   

   Field	Value for Microsoft 365
   From Email Address	Microsoft 365 sending address
   SMTP Host	smtp.office365.com
   SMTP Port	587
   Security	TLS / STARTTLS
   SMTP Username	The same Microsoft 365 sending address
   Authentication	OAuth 2.0 (XOAUTH2)

   Note: For the initial setup, From Email Address and SMTP Username should be the same Microsoft 365 account that was used when obtaining the Authorization Code.

   OAuth 2.0 Settings

   

   Field	Value for Microsoft 365
   Client ID	Application (client) ID from Microsoft Step 2
   Client Secret	Client Secret Value from Microsoft Step 4
   Tenant ID	Directory (tenant) ID from Microsoft Step 2
   Authorization URL	https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize
   Token URL	https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
   Scopes	https://outlook.office.com/SMTP.Send offline_access
   Initial Grant Type	Authorization Code / Refresh Token
   Redirect URI	http://localhost
   Authorization Code	Code obtained in Microsoft Step 6
   Initial Refresh Token	leave empty

   Microsoft 365 (Microsoft Graph API)

   Email Settings

   

    

   Field	Value
   From Email Address	the sending mailbox
   Authentication	Microsoft Graph API (Mail.Send)
   Retry Count	as required
   Retry Interval (seconds)	as required

   OAuth 2.0 Settings — Application permission (Client Credentials)

   

   Field	Value
   Client ID	Application (client) ID from Microsoft Step 2
   Client Secret	Client Secret Value from Microsoft Step 4
   Tenant ID	Directory (tenant) ID from Microsoft Step 2
   Token URL	https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
   Scopes	https://graph.microsoft.com/.default
   Initial Grant Type	Client Credentials
   Send Mail Endpoint	https://graph.microsoft.com/v1.0/users/{from}/sendMail

   The Send Mail Endpoint supports two placeholders, {from} and {SENDER_EMAIL}, both substituted with the From Email Address when the email is sent. A single field therefore drives both the message's From: header and the request URL.

   Note: Authorization URL, Redirect URI, Authorization Code, and Initial Refresh Token are hidden when Initial Grant Type is Client Credentials, as they apply only to the authorization code flow.

   Using the delegated flow instead

   Application permission sends as any licensed mailbox in the tenant with no user interaction, and is the usual choice for a dedicated sending mailbox. To send as a specific consenting user, change these values:

   Field	Value
   Initial Grant Type	Authorization Code / Refresh Token
   Authorization URL	https://login.microsoftonline.com/common/oauth2/v2.0/authorize
   Token URL	https://login.microsoftonline.com/common/oauth2/v2.0/token
   Scopes	https://graph.microsoft.com/Mail.Send offline_access
   Redirect URI	as registered on the app (e.g. http://localhost)
   Authorization Code	obtained from the consent flow
   Send Mail Endpoint	https://graph.microsoft.com/v1.0/me/sendMail
   From Email Address	the address you signed in with
   Tenant ID	leave empty

   Verify the configuration

   1. Click Test OAuth Token. A successful configuration reports OAuth access token obtained successfully.
      
   2. Click Apply Change, save, and deploy the application.
   3. Run the process and confirm the message arrives.

   OAuth 2.0 Settings field reference

   Fields to configure:

   1. Client ID: (required) The application identifier issued by the provider. Sent as client_id in every token request.
   2. Client Secret: The application secret. Stored encrypted. Optional for public clients, but required for the confidential/web-client configurations documented in this article.
   3. Tenant ID: Substituted for the literal {tenant} placeholder in the Authorization URL and Token URL. Required for the Microsoft configuration documented here; left empty for Google.
   4. Authorization URL: The provider's authorization endpoint. Used to construct the consent URL when obtaining the initial authorization code. Reference only; the tool does not call this endpoint.
      

      Provider	Value
      Microsoft	https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize
      Google	https://accounts.google.com/o/oauth2/v2/auth

   5. Token URL (required): The provider's token endpoint. All token requests are sent here.
      

      Provider	Value
      Microsoft	https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
      Google	https://oauth2.googleapis.com/token

   6. Scopes: Space-separated permissions requested from the provider.
      

      Mode and provider	Value
      Google (SMTP)	https://mail.google.com/
      Microsoft SMTP (delegated)	https://outlook.office.com/SMTP.Send offline_access
      Microsoft SMTP (application)	https://outlook.office365.com/.default
      Microsoft Graph (delegated)	https://graph.microsoft.com/Mail.Send offline_access
      Microsoft Graph (application)	https://graph.microsoft.com/.default

   7. Initial Grant Type
      

   8. Option	Use when
      Authorization Code / Refresh Token	Mail is sent as a specific user who has consented. The usual choice.
      Client Credentials	Application-only access with no signed-in user. Supported in Microsoft Graph mode, and in SMTP mode where the provider permits application-only SMTP. Not available with Gmail.

   8. Redirect URI: Must exactly match a redirect URI registered on the OAuth client. Sent during the initial authorization code exchange only.
   9. Authorization Code: The single-use code obtained from the consent flow. Stored encrypted.
   10. Initial Refresh Token: A refresh token obtained out of band and supplied for the initial authorization. Stored encrypted.
       
       Note: Supply either an Authorization Code or an Initial Refresh Token for the first authorization. Once the tool has successfully obtained and stored a token, both fields can be left empty; subsequent sends renew automatically from the stored token.
   11. Send Mail Endpoint (required in Microsoft Graph mode) The Microsoft Graph endpoint the message is posted to. The placeholders {from} and {SENDER_EMAIL} are both substituted with the From Email Address at send time.
       

       Flow	Value
       Application permission	https://graph.microsoft.com/v1.0/users/{from}/sendMail
       Delegated permission	https://graph.microsoft.com/v1.0/me/sendMail

   Test OAuth Token

   The Test OAuth Token button performs a live token request using the values currently entered in the form. If the credentials are valid, a browser dialog confirms that an access token was obtained successfully. If not, the dialog shows the error returned by the provider.
   

   Points to note:

   • Password-type fields display a mask after the configuration is reopened. Re-enter Client Secret, Authorization Code, and Initial Refresh Token before testing, or the masked value is submitted.
   • A successful test consumes the Authorization Code, since redeeming it is what obtains the token. Configure with an Initial Refresh Token if you intend to test repeatedly.
   • The test verifies token acquisition only. It does not open an SMTP connection, so it cannot detect an incorrect host, port, security setting, or a provider-side SMTP AUTH restriction.

   How tokens are stored and renewed

   Access tokens obtained by the tool are encrypted using Joget's data encryption and stored as a system setting. The storage key is derived from the Client ID, resolved Token URL, Scopes, and the sending identity — the SMTP Username in the SMTP modes, or the From Email Address in Microsoft Graph mode. Configurations using different credentials or different sending accounts therefore do not share tokens.

   On each send, the tool resolves a token in this order:

   1. A stored access token that has not yet expired, allowing a 60-second safety margin
   2. The refresh token held inside the stored record
   3. The Initial Refresh Token field
   4. The Authorization Code field, when Initial Grant Type is Authorization Code / Refresh Token
   5. A client_credentials request, when that grant type is selected

   If none of these are available, the tool reports that an authorization code is required.

   Bearer and refresh tokens are never written in plain text. Tokens are only persisted when Joget data encryption is available.

   Additional resources

   The Additional Resources links related articles and tutorials that offer further guidance and information on using the Email Tool and its features. These resources help users understand best practices, explore advanced configurations, and leverage the full potential of Joget's email capabilities. They are invaluable for users seeking to enhance their workflow processes with effective email communication.

   • Email Tool
   • Sending Email
   • User Notification Plugin
   • User Notification Tutorial
   • Send JasperReports PDF in Email Tool
   • Add Signature Form Element as Image into Email Content