Yahoo IMAP/SMTP Exchange using OAUTH2
Basic Requirements

To review the OAuth 2.0 Authorization protocol and for information on the available Yahoo API methods needed to obtain the appropriate OAUTH2 credentials (ie. access_token)

Please visit: https://developer.yahoo.com/oauth2/guide/
Yahoo Oauth2 Guide

All identities supported by Yahoo 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 for information about the available interfaces and to start the review and approval process.

Please visit: https://developer.yahoo.com/mail

Developer Yahoo Mail
IMAP
Yahoo IMAP Protocol Exchange using OAUTHBEARER

Yahoo 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.

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
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’.
RESPONSE
Before base64-encoding After base64-encoding
n,a=@yahoo.com^Aauth=Bearer %2FwQAAAAAAAQWYXBpLXNhYWIubG9naW4uYW9sLmNvbbahHqM4YUdLENu8CHfeoI3lkAKyVpN25pCIaP%2FMkc %2Fetd3zBkJgewo3Uy%2FFv38xwnRWfROcAdRNg1IPIwK%2B82DK0X%2Fxng1w5t5escxLniPqIzxTLzQFsFuUGFV3 wguWHjWOm30wV%2FCQVSoM96kWT%2BxpZ62OOKnjZsKpfdLarH6vmc3vs5tFcMQvTbI0^A^A
bixhdXNlcj11c2Vyb21hZzFAdmVyaXpvbm1lZGlhLmNvbQFhdXRoPUJlYXJlciAlMkZ3UUFBQUFBQUFRV1lYQnBMWE5oW VdJdWJHOW5hVzR1WVc5c0xtTnZiYmFoSHFNNFlVZExFTnU4Q0hmZW9JM2xrQUt5VnBOMjVwQ0lhUCUyRk1rYyUyRmV0Z DN6QmtKZ2V3bzNVeSUyRkZ2Mzh4d25SV2ZST2NBZFJOZzFJUEl3SyUyQjgyREswWCUyRnhuZzF3NXQ1ZXNjeExuaVBxSX p4VEx6UUZzRnVVR0ZWM3dndVdIaldPbTMwd1YlMkZDUVZTb005NmtXVCUyQnhwWjYyT09Lbmpac0twZmRMYXJINnZtYzN2c zV0RmNNUXZUYkkwAQE=
Authentication
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.

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 bixhdXNlcj11c2Vyb21hZzFAdmVyaXpvbm1lZGlhLmNvbQFhdXRoPUJlYXJlciAlMkZ3UUFBQUFBQUFRV1lYQnBMWE 5oWVdJdWJHOW5hVzR1WVc5c0xtTnZiYmFoSHFNNFlVZExFTnU4Q0hmZW9JM2xrQUt5VnBOMjVwQ0lhUCUyRk1 rYyUyRmV0ZDN6QmtKZ2V3bzNVeSUyRkZ2Mzh4d25SV2ZST2NBZFJOZzFJUEl3SyUyQjgyREswWCUyRnhuZzF3NX Q1ZXNjeExuaVBxSXp4VEx6UUZzRnVVR0ZWM3dndVdIaldPbTMwd1YlMkZDUVZTb005NmtXVCUyQnhwWjYyT09L bmpac0twZmRMYXJINnZtYzN2czV0RmNNUXZUYkkwAQE=
S: a003 OK AUTHENTICATE completed
[connection continues...]
RESPONSE
[connection begins]
C: a004 AUTHENTICATE OAUTHBEARER
S: +
C: bixhdXNlcj11c2Vyb21hZzFAdmVyaXpvbm1lZGlhLmNvbQFhdXRoPUJlYXJlciAlMkZ3UUFBQUFBQUFRV1lYQnBMWE 5oWVdJdWJHOW5hVzR1WVc5c0xtTnZiYmFoSHFNNFlVZExFTnU4Q0hmZW9JM2xrQUt5VnBOMjVwQ0lhUCUyRk1 rYyUyRmV0ZDN6QmtKZ2V3bzNVeSUyRkZ2Mzh4d25SV2ZST2NBZFJOZzFJUEl3SyUyQjgyREswWCUyRnhuZzF3NX Q1ZXNjeExuaVBxSXp4VEx6UUZzRnVVR0ZWM3dndVdIaldPbTMwd1YlMkZDUVZTb005NmtXVCUyQnhwWjYyT09L bmpac0twZmRMYXJINnZtYzN2czV0RmNNUXZUYkkwAQE=
S: a003 OK AUTHENTICATE completed
[connection continues...]
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. Yahoo 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 Identification

The Yahoo 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 Yahoo 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 Yahoo 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.

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
SMTP
Yahoo SMTP Protocol Exchange using OAUTHBEARER

To review the OAuth 2.0 Authorization protocol and for information on the available Yahoo API methods needed to obtain the appropriate OAUTH2 credentials (ie. access_token)

Please visit: https://developer.yahoo.com/oauth2/guide/
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
Client Response
The SASL OAUTHBEARER 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 ).
It is important to note that XOAUTH2 authentication is only allowed if SMTP capabilities list as part of the AUTH methods XOAUTH2
RESPONSE
Before base64-encoding After base64-encoding
n,a=useromag1@yahoo.com^Aauth=Bearer %2FwQAAAAAAAQWYXBpLXNhYWIubG9naW4uYW9sLmNvbbahHqM4YUdLENu8CHfeoI3lkAKyVpN25pCIaP%2FMkc%2Fetd3zBkJgewo3Uy%2FFv38xwnRWfROcAdRNg1IPIwK%2B82DK0X%2Fxng1w5t5escxLniPqIzxTLzQFsFuUGFV3wguWHjWOm30wV%2FCQVSoM96kWT%2BxpZ62OOKnjZsKpfdLarH6vmc3vs5tFcMQvTbI0^A^A
bixhdXNlcj11c2Vyb21hZzFAdmVyaXpvbm1lZGlhLmNvbQFhdXRoPUJlYXJlciAlMkZ3UUFBQUFBQUFRV1lYQnBMWE5oWVdJdWJHOW5hVzR1WVc5c0xtTnZiYmFoSHFNNFlVZExFTnU4Q0hmZW9JM2xrQUt5VnBOMjVwQ0lhUCUyRk1rYyUyRmV0ZDN6QmtKZ2V3bzNVeSUyRkZ2Mzh4d25SV2ZST2NBZFJOZzFJUEl3SyUyQjgyREswWCUyRnhuZzF3NXQ1ZXNjeExuaVBxSXp4VEx6UUZzRnVVR0ZWM3dndVdIaldPbTMwd1YlMkZDUVZTb005NmtXVCUyQnhwWjYyT09Lbmpac0twZmRMYXJINnZtYzN2czV0RmNNUXZUYkkwAQE=
Authentication
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.

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
bixhdXNlcj11c2Vyb21hZzFAdmVyaXpvbm1lZGlhLmNvbQFhdXRoPUJlYXJlciAlMkZ3UUFBQUFBQUFRV1lYQnBMWE5 oWVdJdWJHOW5hVzR1WVc5c0xtTnZiYmFoSHFNNFlVZExFTnU4Q0hmZW9JM2xrQUt5VnBOMjVwQ0lhUCUyRk1rYyUyRmV0ZD N6QmtKZ2V3bzNVeSUyRkZ2Mzh4d25SV2ZST2NBZFJOZzFJUEl3SyUyQjgyREswWCUyRnhuZzF3NXQ1ZXNjeExuaVBxSXp4 VEx6UUZzRnVVR0ZWM3dndVdIaldPbTMwd1YlMkZDUVZTb005NmtXVCUyQnhwWjYyT09Lbmpac0twZmRMYXJINnZtYzN2czV0R mNNUXZUYkkwAQE= 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. Yahoo 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
Supported Scopes
OAUTH2 scopes supported by Yahoo
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 Endpoint
Yahoo AOL
  • IMAP
  • imap.mail.yahoo.com
  • SMTP
  • smtp.mail.yahoo.com
  • CALDAV
  • caldav.calendar.yahoo.com
  • CARDDAV
  • carddav.address.yahoo.com
  • IMAP
  • imap.aol.com
  • SMTP
  • smtp.aol.com
  • CALDAV
  • caldav.aol.com
  • CARDDAV
  • carddav.aol.com
Known Endpoints
  • API login Yahoo https://api.login.yahoo.com/.well-known/openid-configuration
{"issuer":"https://api.login.yahoo.com","authorization_endpoint":"https://api.login.yahoo.com/oauth2/request_auth","token_endpoint":"https://api.login.yahoo.com/oauth2/get_token","introspection_endpoint":"https://api.login.yahoo.com/oauth2/introspect","userinfo_endpoint":"https://api.login.yahoo.com/openid/v1/userinfo","token_revocation_endpoint":"https://api.login.yahoo.com/oauth2/revoke","jwks_uri":"https://api.login.yahoo.com/openid/v1/certs","response_types_supported":["code","token","id_token","code token","code id_token","token id_token","code token id_token"],"subject_types_supported":["public"],"grant_types_supported":["authorization_code","refresh_token"],"id_token_signing_alg_values_supported":["ES256","RS256"],"scopes_supported":["openid","openid2","profile","email"],"acr_values_supported":["AAL1","AAL2"],"token_endpoint_auth_methods_supported":["client_secret_basic","client_secret_post"],"claims_supported":["aud","email","email_verified","birthdate","exp","family_name","given_name","iat","iss","locale","name","sub","auth_time"],"response_modes_supported":["query"],"display_values_supported":["page"],"claims_parameter_supported":false,"request_parameter_supported":false,"request_uri_parameter_supported":false}
  • API login AOL https://api.login.aol.com/.well-known/openid-configuration
{{"issuer":"https://api.login.aol.com","authorization_endpoint":"https://api.login.aol.com/oauth2/request_auth","token_endpoint":"https://api.login.aol.com/oauth2/get_token","introspection_endpoint":"https://api.login.aol.com/oauth2/introspect","userinfo_endpoint":"https://api.login.aol.com/openid/v1/userinfo","token_revocation_endpoint":"https://api.login.aol.com/oauth2/revoke","jwks_uri":"https://api.login.aol.com/openid/v1/certs","response_types_supported":["code","token","id_token","code token","code id_token","token id_token","code token id_token"],"subject_types_supported":["public"],"grant_types_supported":["authorization_code","refresh_token"],"id_token_signing_alg_values_supported":["ES256","RS256"],"scopes_supported":["openid","openid2","profile","email"],"acr_values_supported":["AAL1","AAL2"],"token_endpoint_auth_methods_supported":["client_secret_basic","client_secret_post"],"claims_supported":["aud","email","email_verified","birthdate","exp","family_name","given_name","iat","iss","locale","name","sub","auth_time"],"response_modes_supported":["query"],"display_values_supported":["page"],"claims_parameter_supported":false,"request_parameter_supported":false,"request_uri_parameter_supported":false}

Coming soon!

Learn more about our IMAP and SMTP mail services.