Skip to main content

Setting Up Mail.ru with OAuth2

This guide shows you how to set up Mail.ru OAuth2 authentication for IMAP and SMTP access with EmailEngine. EmailEngine will use these credentials to access Mail.ru accounts via the standard IMAP/SMTP protocols with OAuth2 authentication.

Overview​

When you enable OAuth2 for Mail.ru:

  • EmailEngine uses IMAP for reading emails and SMTP for sending
  • Users authenticate once via OAuth2, and EmailEngine automatically refreshes tokens
  • No passwords are stored
  • Works with Mail.ru accounts that have 2FA enabled

Required OAuth2 Scopes​

Mail.ru OAuth2 requires the following scopes:

  • userinfo - Access to basic user profile information
  • mail.imap - Access to IMAP functionality

Step 1: Register an OAuth2 Application​

  1. Go to the Mail.ru OAuth2 Developer Portal

  2. Sign in with your Mail.ru account

  3. Click Create Application (or similar button)

  4. Fill in the application details:

    • Application Name: Your application name (e.g., "EmailEngine Integration")
    • Redirect URI: Your EmailEngine callback URL (e.g., https://your-emailengine-domain/oauth)
    • Scopes: Select userinfo and mail.imap

  5. After creating the application, note down:

    • Client ID (Application ID)
    • Client Secret
Keep Credentials Secure

Never commit your Client ID and Client Secret to version control. Store them securely using environment variables or a secrets manager.

Step 2: Configure EmailEngine​

Option A: Via Web UI​

  1. Open the EmailEngine admin dashboard
  2. Navigate to Configuration > OAuth2 Applications
  3. Click Add New Application
  4. Select Mail.ru as the provider
  5. Enter your credentials:
    • Client ID: Your Mail.ru application ID
    • Client Secret: Your Mail.ru client secret
    • Redirect URL: Must match what you configured in Mail.ru
  6. Save the configuration

Option B: Via API​

Register your Mail.ru OAuth2 application credentials:

curl -XPOST "http://127.0.0.1:3000/v1/oauth2" \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "mailRu",
    "clientId": "YOUR_MAIL_RU_CLIENT_ID",
    "clientSecret": "YOUR_MAIL_RU_CLIENT_SECRET",
    "redirectUrl": "https://your-domain/oauth"
  }'

Response:

{
  "app": "AAABkQw...",
  "provider": "mailRu",
  "enabled": true
}

Step 3: Connect Mail.ru Accounts​

Option A: Using Hosted Authentication Form​

Generate an authentication link for users:

curl -XPOST "http://127.0.0.1:3000/v1/authentication/form" \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "user-mailru-account",
    "type": "oauth2",
    "provider": "mailRu",
    "name": "User Mail.ru Account",
    "redirectUrl": "https://your-app.com/callback"
  }'

Response:

{
  "url": "https://your-emailengine-domain/accounts/new?data=..."
}

Direct users to the returned URL. They will:

  1. Be redirected to Mail.ru's OAuth2 consent screen
  2. Grant permission to your application
  3. Be redirected back to EmailEngine, which stores the tokens
  4. Finally redirect to your specified redirectUrl

Option B: Direct API Registration​

If you already have OAuth2 tokens from Mail.ru, register the account directly:

curl -XPOST "http://127.0.0.1:3000/v1/account" \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "mailru-user",
    "name": "User Name",
    "email": "user@mail.ru",
    "oauth2": {
      "provider": "mailRu",
      "accessToken": "ACCESS_TOKEN_FROM_MAILRU",
      "refreshToken": "REFRESH_TOKEN_FROM_MAILRU",
      "expires": "2024-12-31T23:59:59.000Z"
    }
  }'

Step 4: Verify Connection​

Check that the account connected successfully:

curl "http://127.0.0.1:3000/v1/account/mailru-user" \
  -H "Authorization: Bearer <your-token>"

Expected response:

{
  "account": "mailru-user",
  "name": "User Name",
  "email": "user@mail.ru",
  "state": "connected",
  "oauth2": {
    "provider": "mailRu"
  }
}

The state should be "connected" once EmailEngine establishes the IMAP connection.

Token Management​

EmailEngine automatically handles OAuth2 token refresh for Mail.ru accounts. You can also manually manage tokens if needed.

Get Current Access Token​

Retrieve the current OAuth2 access token for API integrations:

curl "http://127.0.0.1:3000/v1/account/mailru-user/oauth-token" \
  -H "Authorization: Bearer <your-token>"

Response:

{
  "account": "mailru-user",
  "accessToken": "current-access-token",
  "expires": "2024-01-15T12:00:00.000Z"
}

Force Token Refresh​

If you need to force a token refresh:

curl -XPUT "http://127.0.0.1:3000/v1/account/mailru-user/reconnect" \
  -H "Authorization: Bearer <your-token>"

Troubleshooting​

Authentication Errors​

If you see authentication errors:

  1. Verify credentials: Ensure Client ID and Client Secret are correct
  2. Check redirect URL: The redirect URL in EmailEngine must exactly match the one registered in Mail.ru
  3. Verify scopes: Ensure your Mail.ru application has userinfo and mail.imap scopes enabled
  4. Check token expiry: If tokens expired and refresh failed, re-authenticate the user

Connection Issues​

If accounts show as disconnected:

  1. Check account state: Use GET /v1/account/{account} to see the current state
  2. View logs: Check GET /v1/logs/{account} for detailed error messages
  3. Reconnect: Try PUT /v1/account/{account}/reconnect to force reconnection

Common Error Messages​

ErrorCauseSolution
Token request failedInvalid credentials or expired codeRe-authenticate the user
Empty response from APIMail.ru API temporarily unavailableRetry the operation
Invalid JSON responseUnexpected response formatCheck Mail.ru service status

IMAP/SMTP Server Details​

For reference, Mail.ru uses these server settings (handled automatically by EmailEngine when using OAuth2):

ProtocolServerPortSecurity
IMAPimap.mail.ru993SSL/TLS
SMTPsmtp.mail.ru465SSL/TLS

See Also​