OAuth authorization in Yandex.Mail

Mail clients and applications can use the OAuth protocol to access Yandex.Mail mailboxes. When using this protocol, programs don't need to ask for or store usernames and passwords, and users don't need to worry about the security of their passwords.

The Yandex.Mail IMAP and SMTP servers support OAuth authorization. Authorization uses XOAUTH2, which is also used by Gmail.

Setup

To use OAuth authorization in your mail client:

  1. Register your application on Yandex.OAuth with the following permissions:

    • For authorization on the SMTP server — Yandex.MailSending messages via Yandex.Mail on the SMTP protocol.

    • For authorization on the IMAP server — Yandex.MailAccess to read inbox messages or Reading and deleting messages in inbox.

  2. You can request OAuth tokens using any of the available methods (see the Yandex.OAuth documentation). For initial testing, you can use a debugging token.

  3. Set up sending OAuth tokens to Yandex.Mail and processing the server response. The correct interaction with Yandex.Mail servers over IMAP and SMTP is shown below.

Mail server addresses

Access the mail servers at the following addresses:

  • IMAP server — imap.yandex.com:993

  • SMTP server — smtp.yandex.com:465

Interaction with the IMAP server

For authorization on the IMAP server, your program must use the AUTHENTICATE command with the XOAUTH2 mechanism (this mechanism is not mentioned in the output from the CAPABILITY command, but it is supported). Pass the OAuth token and the user's email in the argument.

To make an argument with authorization data:

  1. Create a string with the data:

    user=<username>\@yandex.com\001auth=Bearer <OAuth token>\001\001
  2. Use base64 encoding for the resulting string. For example:

    dXNlcj10ZXN0QHlhbmRleC5ydQFhdXRoPUJlYXJlciBBcmRGZmlnQUFLRndFVWJwWnExRlF4dWZ3SmxycS1wRTJnAQE=

The AUTHENTICATE command must be formed as a single string without line breaks or newlines (the example below is formatted for readability). The sequence of requests and responses for successful IMAP authorization looks something like this:

openssl s_client -connect imap.yandex.com:993 -crlf

<initializing connection>

client: C01 CAPABILITY
server: * CAPABILITY IMAP4rev1 CHILDREN UNSELECT LITERAL+ NAMESPACE XLIST BINARY UIDPLUS ENABLE ID AUTH=PLAIN IDLE MOVE
server: C01 OK CAPABILITY Completed.
client: A01 AUTHENTICATE XOAUTH2 dXNlcj10ZXN0QHlhbmRleC5ydQFhdXRoPUJlYXJlciBBcmRGZmlnQUFLRndFVWJwWnExRlF4dWZ3SmxycS1wRTJnAQE=
server: * CAPABILITY IMAP4rev1 CHILDREN UNSELECT LITERAL+ NAMESPACE XLIST BINARY UIDPLUS ENABLE ID IDLE MOVE
server: A01 OK AUTHENTICATE Completed.

<continue>

Authorization error response

The server returns an error description in response to the AUTHENTICATE command. The sequence of requests and responses for failed IMAP authorization looks something like this:

openssl s_client -connect imap.yandex.com:993 -crlf

<initializing connection>

client: C01 CAPABILITY
server: * CAPABILITY CHILDREN UNSELECT LITERAL+ NAMESPACE XLIST BINARY UIDPLUS ENABLE ID AUTH=PLAIN IDLE MOVE
server: C01 OK CAPABILITY Completed.
client: A01 AUTHENTICATE XOAUTH2 dXNlcj10ZXN0MUB5YW5kZXgucnUBYXV0aD1CZWFyZXIgQXJkRmZpZ0FBS0Z3RVVicFpxMUZReHVmd0pscnEtcEUyZwEB
server: A01 NO [AUTHENTICATIONFAILED] AUTHENTICATE Invalid credentials or IMAP is disabled sc=ANQhQk2BrGkH_101523_7m

<continue>
After the error description, the server provides a string in the format sc=ANQrQk2BrGkH_101523_7m. This is the session ID. You should include it if you contact the Yandex.Mail support service with this error.

Interaction with the SMTP server

When authorizing on the SMTP server, your program should use the AUTH command with the XOAUTH2 mechanism. The access token and username should be encoded and passed in the argument of this command.

The argument with the authorization data is formed the same way as for the IMAP protocol:

  1. Create a string with the data:

    user=<username>\@yandex.com\001auth=Bearer <OAuth token>\001\001
  2. Use base64 encoding for the resulting string. For example:

    dXNlcj10ZXN0QHlhbmRleC5ydQFhdXRoPUJlYXJlciBBcmRGZmlnQUFLRndFVWJwWnExRlF4dWZ3SmxycS1wRTJnAQE=

The sequence of requests and responses for successful SMTP authorization looks like this:

openssl s_client -connect smtp.yandex.com:465 -crlf

<initializing connection>

server: 220 smtp2o.mail.yandex.net ESMTP (Want to use Yandex.Mail for your domain? Visit http://pdd.yandex.ru)
client:EHLO sender.example.com
server:250-smtp2o.mail.yandex.net
server:250-8BITMIME
server:250-PIPELINING
server:250-SIZE 42991616
server:250-AUTH LOGIN PLAIN XOAUTH2
server:250-DSN
server:250 ENHANCEDSTATUSCODES
client:AUTH XOAUTH2 dXNlcj10ZXN0QHlhbmRleC5ydQFhdXRoPUJlYXJlciBBcmRGZmlnQUFLRndFVWJwWnExRlF4dWZ3SmxycS1wRTJnAQE=
server:235 2.7.0 Authentication successful.

<continue>

The AUTH command must be formed as a single string without newlines (the example is formatted for readability).

Authorization error response

The server returns an error description with the code 535 in response to the AUTH command.

Example of requests and responses for failed SMTP authorization:

openssl s_client -connect smtp.yandex.com:465 -crlf

<initializing connection>

server: 220 smtp2o.mail.yandex.net ESMTP (Want to use Yandex.Mail for your domain? Visit http://pdd.yandex.ru)
client:EHLO sender.example.com
server:250-smtp2o.mail.yandex.net
server:250-8BITMIME
server:250-PIPELINING
server:250-SIZE 42991616
server:250-AUTH LOGIN PLAIN XOAUTH2
server:250-DSN
server:250 ENHANCEDSTATUSCODES
client:AUTH XOAUTH2 dXNlcj10ZXN0MUB5YW5kZXgucnUBYXV0aD1CZWFyZXIgQXJkRmZpZ0FBS0Z3RVVicFpxMUZReHVmd0pscnEtcEUyZwEB
server:535 5.7.8 Error: authentication failed: Invalid user or password!

<continue>

If the authorization string was formed incorrectly, the error will be:

server: 535 5.7.8 Error: authentication failed:Invalid format.