Authenticate an IMAP, POP or SMTP connection using OAuth

Learn how to use OAuth authentication to connect with IMAP, POP or SMTP protocols and access email data for Office 365 users.

OAuth2 support for IMAP, POP, SMTP protocols as described below is not supported for Outlook.com users.

If you're not familiar with OAuth 2.0, start by reading the Microsoft identity platform (v2.0) overview. That document introduces you to different components of Microsoft identity platform, including SDKs.

You can use the OAuth authentication service provided by Azure Active Directory to enable your application to connect with IMAP, POP or SMTP protocols to access Exchange Online in Office 365. To use OAuth with your application you need to:

  1. Register your application with Azure Active Directory.
  2. Configure your application in Azure Active Directory.
  3. Get an access token from a token server.
  4. Authenticate connection requests with an access token.

Register your application

To use OAuth, an application must be registered with Azure Active Directory.

Follow the instructions listed in Register an application with the Microsoft identity platform to create a new application.

Configure your application

Follow the instructions listed in Configure a client application to access web APIs

Make sure to add one or more of the following permission scopes that correspond to the protocols you would like to integrate with. In the Add a permission wizard, select Microsoft Graph and then Delegated permissions to find the following permission scopes listed.

Protocol Permission scope
IMAP IMAP.AccessAsUser.All
POP POP.AccessAsUser.All
SMTP AUTH SMTP.Send

Get an access token

You can use one of our MSAL client libraries to fetch an access token from your client application.

Alternatively, you can select an appropriate flow from the following list and follow the corresponding steps to call the underlying identity platform REST APIs and retrieve an access token.

  1. OAuth2 authorization code flow
  2. OAuth2 Device authorization grant flow

OAuth access to IMAP, POP, SMTP AUTH protocols via OAuth2 client credentials grant flow is not supported. If your application needs persistent access to all mailboxes in a Microsoft 365 organization, we recommend that you use the Microsoft Graph APIs which allow access without a user, enable granular permissions and let administrators scope such access to a specific set of mailboxes.

Make sure to specify the full scopes, including Outlook resource URLs, when authorizing your application and requesting an access token.

Protocol Permission scope string
IMAP https://outlook.office.com/IMAP.AccessAsUser.All
POP https://outlook.office.com/POP.AccessAsUser.All
SMTP AUTH https://outlook.office.com/SMTP.Send

In addition, you can request for offline_access scope. When a user approves the offline_access scope, your app can receive refresh tokens from the Microsoft identity platform token endpoint. Refresh tokens are long-lived. Your app can get new access tokens as older ones expire.

Authenticate connection requests

You can initiate a connection to Office 365 mail servers using the IMAP and POP email settings for Office 365.

SASL XOAUTH2

OAuth integration with requires your application to use SASL XOAUTH2 format for encoding and transmitting the access token. SASL XOAUTH2 encodes the username, access token together in the following format:

base64("user=" + userName + "^Aauth=Bearer " + accessToken + "^A^A")

^A represents a Control + A (%x01).

For example, the SASL XOAUTH2 format to access test@contoso.onmicrosoft.com with access token EwBAAl3BAAUFFpUAo7J3Ve0bjLBWZWCclRC3EoAA is:

base64("user=test@contoso.onmicrosoft.com^Aauth=Bearer EwBAAl3BAAUFFpUAo7J3Ve0bjLBWZWCclRC3EoAA^A^A")

After base64 encoding, this translates to the following string. Note that line breaks are inserted for readability.

dXNlcj10ZXN0QGNvbnRvc28ub25taWNyb3NvZnQuY29tAWF1dGg9QmVhcmVy
IEV3QkFBbDNCQUFVRkZwVUFvN0ozVmUwYmpMQldaV0NjbFJDM0VvQUEBAQ==

SASL XOAUTH2 authentication for shared mailboxes in Office 365

In case of shared mailbox access using OAuth, application needs to obtain the access token on behalf of a user but replace the userName field in the SASL XOAUTH2 encoded string with the email address of the shared mailbox.

IMAP Protocol Exchange

To authenticate a IMAP server connection, the client will have to respond with an AUTHENTICATE command in the following format:

AUTHENTICATE XOAUTH2 <base64 string in XOAUTH2 format>

Sample client-server message exchange that results in an authentication success:

[connection begins]
C: C01 CAPABILITY
S: * CAPABILITY … AUTH=XOAUTH2
S: C01 OK Completed
C: A01 AUTHENTICATE XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cBAQ==
S: A01 OK AUTHENTICATE completed.

Sample client-server message exchange that results in an authentication failure:

[connection begins]
S: * CAPABILITY … AUTH=XOAUTH2
S: C01 OK Completed
C: A01 AUTHENTICATE XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cBAQ==
S: A01 NO AUTHENTICATE failed.

POP Protocol Exchange

To authenticate a POP server connection, the client will have to respond with an AUTH command split into two lines in the following format:

AUTH XOAUTH2 
<base64 string in XOAUTH2 format>	

Sample client-server message exchange that results in an authentication success:

[connection begins]	
C: AUTH XOAUTH2 	
S: +	
C: dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYX	
JlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0	
Q2cBAQ==	
S: +OK User successfully authenticated.	
[connection continues...]	

Sample client-server message exchange that results in an authentication failure:

[connection begins]	
C: AUTH XOAUTH2 	
S: +	
C: dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlY	
XJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMj	
l0Q2cBAQ=	
S: -ERR Authentication failure: unknown user name or bad password.	

SMTP Protocol Exchange

To authenticate a SMTP server connection, the client will have to respond with an AUTH command in the following format:

AUTH XOAUTH2 <base64 string in XOAUTH2 format>

Sample client-server message exchange that results in an authentication success:

[connection begins]
C: auth xoauth2
S: 334
C: dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlY
XJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMj
l0Q2cBAQ==
S: 235 2.7.0 Authentication successful
[connection continues...]

Sample client-server message exchange that results in an authentication failure:

[connection begins]
C: auth xoauth2
S: 334
C: dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlY
XJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMj
l0Q2cBAQ==
S: 535 5.7.3 Authentication unsuccessful [SN2PR00CA0018.namprd00.prod.outlook.com]

See also