OAuth 2.0 Support

(As of version 3.3.010.01)

Starting in April 2026, basic authentication for Client Submission (SMTP AUTH) will be retired, and it will no longer be possible to send email using a password. Support for the more secure OAuth 2.0 protocol using access tokens has been added to the Merge and DocOriginSendMailServer executables, including:

• Access token retrieval and refresh
• Sending email with the obtained access token

All required OAuth 2.0 request parameters must be specified in the DocOriginSendMailServer.prm file using the prefix -oauth.*. If OAuth-related parameters (with the -oauth. prefix) are not present in the .prm file, DocOrigin falls back to the legacy approach using basic authorization (username and password).

Flexible Email Provider Support

You must configure an application for obtaining an OAuth 2.0 access token, which is then used to authorize email sending. Guides for Outlook / Microsoft 365 Application Configuration and Gmail Application Configuration are available as examples.

OAuth request parameters are defined by the email provider. All parameter names must follow the provider's official documentation. Templates SampleOAuthOutlook_DocOriginSendMailServer.prm and SampleOAuthGmail_DocOriginSendMailServer.prm are available as examples in the ../DocOrigin/DO/Bin folder.

Other email providers can be supported by configuring the application to obtain OAuth 2.0 access tokens and adding the required parameters for the specific client to the PRM file with the oauth.* prefix.

Mandatory Parameters for Access Token Requests

The access token can be obtained using two different OAuth 2.0 flows:

1. Client credentials flow - Access token is obtained by using client_id and client_secret specified in prm file (no refresh token in this case).
   

   Gmail (Important Note) - Gmail does not support the client credentials flow. Google supports service accounts for server-to-server interactions — your app authenticates as a service account identity using a signed JWT to obtain access tokens. This does not require a refresh token, but does not work for regular Gmail accounts unless domain-wide delegation is enabled by a Google Workspace administrator

2. Authorization code / Refresh Token flow - In this flow, the access token is obtained using a client_id and a previously obtained refresh_token. This approach requires two manual steps:
   1. Obtain an authorization code via user consent.
   2. Exchange the authorization code for a refresh token, which is then used for automated access token retrieval.

-smtphost smtp-mail.outlook.com
-smtpport 587
-curlOptions --ssl-reqd
-smtpuser {YOUR_USER_EMAIL}
-from {YOUR_USER_EMAIL}

-oauth.requestRetryCount 3
-oauth.requestSleepTimer 500
-oauth.accessTokenLifetime 3599
-oauth.url https://login.microsoftonline.com/{YOUR_TENANT_ID}/oauth2/v2.0/token
-oauth.client_id {YOUR_CLIENT_ID}
-oauth.client_secret {YOUR_CLIENT_SECRET}
-oauth.scope https://outlook.office365.com/.default
-oauth.grant_type client_credentials

-smtphost smtp.gmail.com
-smtpport 587
-curlOptions --ssl-reqd
-smtpuser {YOUR_USER}@gmail.com
-from {YOUR_USER}@gmail.com

-oauth.requestRetryCount 3
-oauth.requestSleepTimer 500
-oauth.accessTokenLifetime 3599
-oauth.url https://oauth2.googleapis.com/token
-oauth.client_id {YOUR_CLIENT_ID}
-oauth.client_secret {YOUR_CLIENT_SECRET}
-oauth.refresh_token {YOUR_REFRESH_TOKEN}
-oauth.grant_type refresh_token

Optional Parameters

1. Access Token Retrieval Reliability and Retry Mechanism
   To make the access token retrieval mechanism more reliable in cases of temporary internet connectivity issues or backend service issues, a request retry mechanism has been implemented. This mechanism can be configured using the following parameters:
   

   -oauth.requestRetryCount 3 (number of retry attempts; default is 1) 
   -oauth.requestSleepTimer 1000 (delay between retries in milliseconds; default is 0)

2. Access Token Lifetime Handling
   An additional optional parameter is provided to manage the timing of automated access token updates and to prevent token expiration. DocOrigin refreshes the access token 5 minutes before the configured token lifetime expires.
   

   -oauth.accessTokenLifetime 3599 (access token life time in seconds, 3599 by default)