Yahoo Developer Network

Verizon Media IMAP/SMTP Exchange using OAUTH2¶

Basic Requirements

To review the OAuth 2.0 Authorization protocol and for information on the available Verizon Media API methods needed to obtain the appropriate OAUTH2 credentials (ie. access_token), please visit the following documentation:

https://developer.yahoo.com/oauth2/guide/

All identities supported by Verizon Media share the same identify infrastructure. This means applications can use the same mechanism to obtain Oauth2 tokens for both Yahoo and AOL accounts. However applications and services need a separate set of client credentials for each namespace.

Applications and services also need access to the mail scope. If that is not already available or approved please visit https://developer.verizonmedia.com/mail for information about the available interfaces and to start the review and approval process.

Verizon Media IMAP Protocol Exchange using OAUTHBEARER

Verizon Media IMAP uses the standard Simple Authentication and Security Layer (SASL), via the IMAP AUTHENTICATE command, to authenticate users. The SASL OAUTHBEARER mechanism enables clients to provide OAuth 2.0 credentials for authentication.

It is important to note that OAUTHBEARER authentication is only allowed if AUTH=OAUTHBEARER is specified in the IMAP capability response. For example:

C: a001 CAPABILITY
S: * CAPABILITY IMAP4rev1 SASL-IR AUTH=PLAIN AUTH=XOAUTH2
AUTH=OAUTHBEARER ID MOVE NAMESPACE XYMHIGHESTMODSEQ UIDPLUS LITERAL+ CHILDREN X-MSG-EXT

S: a001 OK CAPABILITY completed

Constructing the Initial Client Request

The SASL OAUTHBEARER initial client response contains the following parts:

{Authentication Identity} or Sasl Name	GS2 authorization id as defined in RFC 5801. Mailbox email is provided here
{Auth Token}	OAUTH2 access_token prefixed with "Bearer"
Host	(Optional) Contains the host to which client connected.
Port	(Optional) Contains the port to which client connected.

The IMAP protocol uses the following base64-encoded value string when authenticating with XOAuth2.

base64("n,a=user@yahoo.com,^Ahost=imap.mail.yahoo.com^Aport=993^Aauth=Bearer vF9dft4qmTc2Nvb3RlckBhbHRhdmlzdGEuY29tCg==^A^A")

^A represents a Control+A (\001). Note that there is a space after ‘Bearer’.

For example, before base64-encoding, the initial client response might look like this:

n,a=@yahoo.com^Aauth=Bearer
%2FwQAAAAAAAQWYXBpLXNhYWIubG9naW4uYW9sLmNvbbahHqM4YUdLENu8CHfeoI3lkAKyVpN25pCIaP%2FMkc%2Fetd3zBkJgewo3Uy%2FFv38xwnRWfROcAdRNg1IPIwK%2B82DK0X%2Fxng1w5t5escxLniPqIzxTLzQFsFuUGFV3wguWHjWOm30wV%2FCQVSoM96kWT%2BxpZ62OOKnjZsKpfdLarH6vmc3vs5tFcMQvTbI0^A^A

After base64-encoding, this becomes:

bixhdXNlcj11c2Vyb21hZzFAdmVyaXpvbm1lZGlhLmNvbQFhdXRoPUJlYXJlciAlMkZ3UUFBQUFBQUFRV1lYQnBMWE5oWVdJdWJHOW5hVzR1WVc5c0xtTnZiYmFoSHFNNFlVZExFTnU4Q0hmZW9JM2xrQUt5VnBOMjVwQ0lhUCUyRk1rYyUyRmV0ZDN6QmtKZ2V3bzNVeSUyRkZ2Mzh4d25SV2ZST2NBZFJOZzFJUEl3SyUyQjgyREswWCUyRnhuZzF3NXQ1ZXNjeExuaVBxSXp4VEx6UUZzRnVVR0ZWM3dndVdIaldPbTMwd1YlMkZDUVZTb005NmtXVCUyQnhwWjYyT09Lbmpac0twZmRMYXJINnZtYzN2czV0RmNNUXZUYkkwAQE=

IMAP Login with SASL OAUTHBEARER Mechanism

The client invokes the AUTHENTICATE command with the mechanism parameter of XOAUTH2 and the initial client response as constructed above. For example:

[connection begins]
C: a002 CAPABILITY
S: * CAPABILITY IMAP4rev1 SASL-IR AUTH=PLAIN AUTH=XOAUTH2
AUTH=OAUTHBEARER ID MOVE NAMESPACE XYMHIGHESTMODSEQ UIDPLUS LITERAL+ CHILDREN X-MSG-EXT
S: a002 OK CAPABILITY completed
C: a003 AUTHENTICATE OAUTHBEARER bixhdXNlcj11c2Vyb21hZzFAdmVyaXpvbm1lZGlhLmNvbQFhdXRoPUJlYXJlciAlMkZ3UUFBQUFBQUFRV1lYQnBMWE5oWVdJdWJHOW5hVzR1WVc5c0xtTnZiYmFoSHFNNFlVZExFTnU4Q0hmZW9JM2xrQUt5VnBOMjVwQ0lhUCUyRk1rYyUyRmV0ZDN6QmtKZ2V3bzNVeSUyRkZ2Mzh4d25SV2ZST2NBZFJOZzFJUEl3SyUyQjgyREswWCUyRnhuZzF3NXQ1ZXNjeExuaVBxSXp4VEx6UUZzRnVVR0ZWM3dndVdIaldPbTMwd1YlMkZDUVZTb005NmtXVCUyQnhwWjYyT09Lbmpac0twZmRMYXJINnZtYzN2czV0RmNNUXZUYkkwAQE=
S: a003 OK AUTHENTICATE completed
[connection continues...]

The AUTHENTICATE command also supports a continuation response, as follows:

[connection begins]
C: a004 AUTHENTICATE OAUTHBEARER
S: +
C: bixhdXNlcj11c2Vyb21hZzFAdmVyaXpvbm1lZGlhLmNvbQFhdXRoPUJlYXJlciAlMkZ3UUFBQUFBQUFRV1lYQnBMWE5oWVdJdWJHOW5hVzR1WVc5c0xtTnZiYmFoSHFNNFlVZExFTnU4Q0hmZW9JM2xrQUt5VnBOMjVwQ0lhUCUyRk1rYyUyRmV0ZDN6QmtKZ2V3bzNVeSUyRkZ2Mzh4d25SV2ZST2NBZFJOZzFJUEl3SyUyQjgyREswWCUyRnhuZzF3NXQ1ZXNjeExuaVBxSXp4VEx6UUZzRnVVR0ZWM3dndVdIaldPbTMwd1YlMkZDUVZTb005NmtXVCUyQnhwWjYyT09Lbmpac0twZmRMYXJINnZtYzN2czV0RmNNUXZUYkkwAQE=
C: a004 OK AUTHENTICATE completed
[connection continues..]

Things to note about the IMAP protocol exchange:

The IMAP AUTHENTICATE command is documented in RFC 3501.
Single line login (sending the initial client response in the first line of the AUTHENTICATE command) is only allowed if SASL-IR is specified in the capability response. The SASL-IR capability is documented in RFC 4959.
The AUTH=OAUTHBEARER capability declares that the server supports the SASL mechanism defined in RFC 7628, and that this mechanism is activated by specifying OAUTHBEARER as the first argument to the AUTHENTICATE command.
AUTHENTICATE SASL commands are multi-line as specified by IMAP RFC. Verizon Media also supports SASL-IR as defined in RFC 4959 to allow clients complete successful AUTHENTICATE on a single line or request.

Error Response

Authentication failures are also returned via the IMAP AUTHENTICATE command:
[connection begins]
C: a005 CAPABILITY
S: * CAPABILITY IMAP4rev1 SASL-IR AUTH=PLAIN AUTH=XOAUTH2
AUTH=OAUTHBEARER ID MOVE NAMESPACE XYMHIGHESTMODSEQ UIDPLUS LITERAL+ CHILDREN
X-MSG-EXT
S: a005 OK CAPABILITY completed
C: a006 AUTHENTICATE OAUTHBEARER {......}
S: a006 BAD [AUTHENTICATIONFAILED] AUTHENTICATE Invalid credentials

Currently, a NO response is returned upon authentication failure. This error response is subject to change based on industry standards.

a003 NO [AUTHENTICATIONFAILED] AUTHENTICATE Server error - Please try again later

IMAP Features

Client Indentification

The Verizon Media IMAP server supports the IMAP ID command https://www.ietf.org/rfc/rfc2971.txt to gather statistics and facilitate troubleshooting. An IMAP client connecting to the Verizon Media servers should issue the ID command with the following attributes: NAME, VERSION, OS, OS-VERSION.

NAME should be the partner name or the ID assigned during the approval process.
example: "name" "iPhone Mail"
"name" "com.android.email"
"name" "yahoo.com"

VERSION is the version of that client. It's useful when watching for changes in behavior OS & OS-VERSION are additional info for determining client environment specific issues.

A full ID command looks like this:
C: a007 ID ("name" "<'client name'>" "version" "<'client version'>" "os" "<'client os'>" "os-version" "<'client os version'>")

Mail Message Move

The Verizon Media IMAP server supports the IMAP MOVE command https://tools.ietf.org/html/rfc6851 to easily move a message to a different mailbox. The move command can more efficiently move a message to a new folder than the typical COPY/STORE/EXPUNGE command sequence. The MOVE command has the added benefit of not affecting any mailbox quotas as there is only ever one copy of the message.

The typical command sequence:

C: a008 copy 1 trash
S: a008 OK [COPYUID 1 23094753 25329933] COPY completed
C: a009 store 1 +flags \deleted
S: * 1 FETCH (FLAGS (\Deleted))
C: a009 OK STORE completed
C: a010 uid expunge 23094753
S: * 1 EXPUNGE
S: * 5373 EXISTS
S: a010 OK UID EXPUNGE completed

becomes:

C: a011 move 1 trash
S: * OK [COPYUID 1 23114800 25329934]
S: * 1 EXPUNGE
S: * 5372 EXISTS
S: a011 OK MOVE completed

Verizon Media SMTP Protocol Exchange using OAUTHBEARER

https://developer.yahoo.com/oauth2/guide/

Verizon Media SMTP uses the standard Simple Authentication and Security Layer (SASL), via the SMTP AUTH command, to authenticate users. The SASL OAUTHBEARER mechanism enables clients to provide OAuth 2.0 credentials for authentication.

It is important to note that XOAUTH2 authentication is only allowed if SMTP capabilities list as part of the AUTH methods XOAUTH2. For example:

C: EHLO my.mua.host.name
S: 250-mtaout-aah01.mx.aol.com
S: 250-PIPELINING
S: 250-SIZE 36700160
S: 250-ETRN
S: 250-STARTTLS
S: 250-AUTH XAOL-UAS-MB XOAUTH2 OAUTHBEARER PLAIN LOGIN
S: 250-AUTH=XAOL-UAS-MB XOAUTH2 OAUTHBEARER PLAIN LOGIN
S: 250-ENHANCEDSTATUSCODES
S: 250-8BITMIME
S: 250 DSN

Constructing the Initial Client Response

The SASL OAUTHBEARER initial client response contains the following parts:

{Authentication Identity} or Sasl Name	GS2 authorization id as defined in RFC 5801. Mailbox email is provided here
{Auth Token}	OAUTH2 access_token prefixed with "Bearer"
Host	(Optional) Contains the host to which client connected.
Port	(Optional) Contains the port to which client connected.

The SMTP protocol uses the following base64-encoded value string when authenticating with XOAuth2.

base64("n,a=user@yahoo.com,^Ahost=smtp.mail.yahoo.com^Aport=465^Aauth=Bearer vF9dft4qmTc2Nvb3RlckBhbHRhdmlzdGEuY29tCg==^A^A"

^A represents a Control+A (\001).

For example, before base64-encoding, the initial client response might look like this:

n,a=useromag1@yahoo.com^Aauth=Bearer %2FwQAAAAAAAQWYXBpLXNhYWIubG9naW4uYW9sLmNvbbahHqM4YUdLENu8CHfeoI3lkAKyVpN25pCIaP%2FMkc%2Fetd3zBkJgewo3Uy%2FFv38xwnRWfROcAdRNg1IPIwK%2B82DK0X%2Fxng1w5t5escxLniPqIzxTLzQFsFuUGFV3wguWHjWOm30wV%2FCQVSoM96kWT%2BxpZ62OOKnjZsKpfdLarH6vmc3vs5tFcMQvTbI0^A^A

After base64-encoding, this becomes:

SMTP Authentication with SASL OAUTHBEARER Mechanism

The client invokes the AUTH command with the mechanism parameter of XOAUTH2 and the initial client response as constructed above. For example:

[connection begins]
C: EHLO my.mua.host.name
S: 250-mtaout-aah01.mx.aol.com
S: 250-PIPELINING
S: 250-SIZE 36700160
S: 250-ETRN
S: 250-STARTTLS
S: 250-AUTH XAOL-UAS-MB XOAUTH2 PLAIN LOGIN
S: 250-AUTH=XAOL-UAS-MB XOAUTH2 PLAIN LOGIN
S: 250-ENHANCEDSTATUSCODES
S: 250-8BITMIME
S: 250 DSN
C: AUTH OAUTHBEARER
bixhdXNlcj11c2Vyb21hZzFAdmVyaXpvbm1lZGlhLmNvbQFhdXRoPUJlYXJlciAlMkZ3UUFBQUFBQUFRV1lYQnBMWE5oWVdJdWJHOW5hVzR1WVc5c0xtTnZiYmFoSHFNNFlVZExFTnU4Q0hmZW9JM2xrQUt5VnBOMjVwQ0lhUCUyRk1rYyUyRmV0ZDN6QmtKZ2V3bzNVeSUyRkZ2Mzh4d25SV2ZST2NBZFJOZzFJUEl3SyUyQjgyREswWCUyRnhuZzF3NXQ1ZXNjeExuaVBxSXp4VEx6UUZzRnVVR0ZWM3dndVdIaldPbTMwd1YlMkZDUVZTb005NmtXVCUyQnhwWjYyT09Lbmpac0twZmRMYXJINnZtYzN2czV0RmNNUXZUYkkwAQE= S: 235 2.7.0 Authentication successful

[connection continues...]

Things to note about the SMTP protocol exchange:

The SMTP AUTH command is documented in RFC 4954.
Single line login (sending the initial client response in the first line of the AUTH command) is only allowed if SASL-IR is specified in the capability response. The SASL-IR capability is documented in RFC 4959.
The AUTH=OAUTHBEARER capability declares that the server supports the SASL mechanism defined in RFC 7628, and that this mechanism is activated by specifying OAUTHBEARER as the first argument to the AUTHENTICATE command.
AUTHENTICATE SASL commands are multi-line. Verizon Media also supports SASL-IR as defined in RFC 4959 to allow clients complete successful AUTHENTICATE on a single line or request.

Error Response

Authentication failures are also returned via the SMTP AUTHENTICATE command:
[connection begins]
C: EHLO my.mua.host.name
S: 250-mtaout-aah01.mx.aol.com
S: 250-PIPELINING
S: 250-SIZE 36700160
S: 250-ETRN
S: 250-STARTTLS
S: 250-AUTH XAOL-UAS-MB XOAUTH2 PLAIN LOGIN
S: 250-AUTH=XAOL-UAS-MB XOAUTH2 PLAIN LOGIN
S: 250-ENHANCEDSTATUSCODES
S: 250-8BITMIME
S: 250 DSN
C: AUTH OAUTHBEARER {......}

S: 535 5.7.8 Error: authentication failed: authentication failure§

§ Currently, a 535 response is returned upon authentication failure. This error response is subject to change based on industry standards

OAUTH2 scopes supported by Verizon Media

Please refer to https://developer.yahoo.com/oauth2/guide/yahoo_scopes/

Supported mail, contacts and calendar scopes are also listed in your YDN application profile once approved.

email
profile
mail-r - mail read
mail-w - mail write
sdct-r - contacts read
sdct-w - contacts write
ycal-r - calendar read
ycal-w - calendar write

Customer Data Endpoints

IMAP: imap.mail.yahoo.com; imap.aol.com
SMTP: smtp.mail.yahoo.com; smtp.aol.com
CALDAV: caldav.calendar.yahoo.com; caldav.aol.com
CARDDAV: carddav.address.yahoo.com; carddav.aol.com