Authenticating Yahoo accounts with Nylas

Nylas supports two ways to authenticate users who have Yahoo as their provider: using Yahoo’s OAuth and Nylas’ Bring Your Own (BYO) Authentication, or by having them create an app password and using that password with Nylas’ BYO or Hosted IMAP authentication

We strongly recommend using Yahoo’s OAuth method instead of authenticating using IMAP. This gives you more secure access to your users’ data.

Set up Yahoo OAuth and Nylas Bring Your Own Authentication

Before you authenticate users with Yahoo’s OAuth and Nylas’ BYO Authentication, you need to set up your environment and authentication flow:

Request access to Yahoo data.
Set up an OAuth-client endpoint that can perform an OAuth handshake.
Create and configure a Yahoo auth app.
Create a Yahoo connector.
Use information from the OAuth process to make BYO Authentication requests to Nylas and create grants for your users.

Request access to Yahoo data

Create a Yahoo account that only your organization’s administrators can access.
Submit a Yahoo Mail API Access form to Yahoo. This is required if you want to use OAuth to access Yahoo’s IMAP and SMTP servers. Make sure you mention somewhere in the form that you’re using Nylas to connect.
- Email address: Enter the email address that you created in step 1.
- API required: Select IMAP.
- Your YDN account: Enter the email address that you created in step 1.
Yahoo sends you a Yahoo Mail Products Commercial Access Agreement. Review the form, sign it, and send it back to Yahoo.

Yahoo sends you a message to notify you when they approve your data access request, or to ask for more information (if needed).

Set up OAuth-client endpoint

After you request access to Yahoo data, you need to set up an OAuth-client endpoint (also called a “redirect URI”) in your project. This endpoint must be able to accept requests from Yahoo, extract information from the requests to complete an OAuth handshake process, then use the resulting refresh token to create a Nylas grant using BYO Authentication.

Take note of your OAuth-client endpoint URI. You’ll need it when you create your Yahoo auth app.

Create Yahoo auth app

Sign in to the Yahoo Apps dashboard using your admin Yahoo account.
Select Create an app and fill out the information.
- Application name: Enter a brief, descriptive name for your application.
- Description: Describe your application (for example, the region you’ll be using it for).
- Homepage URL: (Optional) Enter your application’s homepage URL.
- Redirect URI(s): Enter your OAuth-client endpoint URI. Registering a redirect URI might take up to 24 hours. You might experience inconsistencies when trying to log in to your Yahoo account during that time.
- OAuth client type: Select Confidential client.
- API permissions:
  - Select Mail. If you plan to use Nylas to send or modify messages, select Read/Write. If you don’t send or modify messages, select Read.
  - Select OpenID connect permissions, then select Email and Profile.
Click Create app.
On the next page, Yahoo displays your app’s client ID and secret. Take note of them, because you’ll need them when you create a Yahoo connector.
Be sure to save the client secret value somewhere secure, like a secrets manager. For best practices, see Store secrets securely.

Create Yahoo connector

After you create a Yahoo auth app, you can create a Yahoo connector for your Nylas application.

To create a connector using the Nylas API, make a Create Connector request that specifies "provider": "yahoo".

Your scope array must match the scopes you request in your Yahoo auth app. If you request Mail Read/Write in your auth app, specify mail-w in your request. If you request Mail Read, specify mail-r instead. If you try to request both mail-w and mail-r, Nylas returns an error.

curl -X POST 'https://api.us.nylas.com/v3/connectors' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "provider": "yahoo",
    "settings": {
      "client_id": "<YAHOO_CLIENT_ID>",
      "client_secret": "<YAHOO_CLIENT_SECRET>"
    },
    "scope": [
      "email",
      "mail-w"
    ]
  }'

To make a connector in the Nylas Dashboard…

Select Connectors in the left navigation.
On the next screen, find Yahoo and click the plus symbol (+).
Enter your Yahoo OAuth client ID and Yahoo OAuth client secret.
Select either the mail-r or mail-w scope, depending on the scopes you requested in your Yahoo auth app.
Save your changes.

Create grants with Yahoo OAuth

When your OAuth-client endpoint receives a request, you use the information it provides to fill out the following URL template:

https://api.login.yahoo.com/oauth2/request_auth?client_id=<YAHOO_CLIENT_ID>&redirect_uri=<CALLBACK_URI>&response_type=code

When a user requests this URL, they’re redirected to Yahoo’s login page. They then log in to their account and confirm that they’re allowing Nylas to access their Yahoo Mail data. After they authenticate, Yahoo returns a refresh token that you use to make a Bring Your Own Authentication request. This completes the Yahoo OAuth flow and creates a Nylas grant for the user.

Overall, the Yahoo OAuth flow follows these steps:

Yahoo sends a GET request that includes the code query parameter.

Your OAuth-client endpoint extracts the code value and makes a token request to Yahoo.

curl --request POST \
  --location 'https://api.login.yahoo.com/oauth2/get_token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'redirect_uri=<NYLAS_REDIRECT_URI>' \
  --data-urlencode 'code=<YAHOO_CODE>' \
  --data-urlencode 'client_id=<YAHOO_CLIENT_ID>' \
  --data-urlencode 'client_secret=<YAHOO_CLIENT_SECRET>'

Yahoo responds with a refresh_token.

{
  "access_token": "<ACCESS_TOKEN>",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "<REFRESH_TOKEN>",
  "xoauth_yahoo_guid": "<YAHOO_GUID>"
}

Your OAuth-client endpoint makes a BYO Authentication request that includes the Yahoo refresh_token.

curl -X POST 'https://api.us.nylas.com/v3/connect/custom' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "provider": "yahoo",
    "settings": {
      "refresh_token": "<YAHOO_REFRESH_TOKEN>"
    }
  }'

Nylas creates a grant for the user and returns its grant_id.

Authenticate Yahoo grants with app password

If you’re not able to set up a Yahoo OAuth application, there are two ways to authenticate Yahoo users: you can either use Hosted IMAP and an app password, or use Bring Your Own Authentication and an app password. For both of these methods, the user first needs to create an app password.

Create Yahoo app password

If your Yahoo users authenticate using IMAP, they need to create an app password. They’ll use this in place of their regular email password when authenticating.

Sign in to Yahoo Mail.
Navigate to Account info > Account security.
At the bottom of the screen, select Generate app password.
Follow the steps to generate a new app password.

These steps also work for users who have two-factor authentication enabled.

For more details, read the generate third-party app passwords article from Yahoo.

If the Yahoo responds with an incorrect credential error, Nylas prompts the user with an error message and a hint with a link to Yahoo guide about creating an application password

Create grants with app password and Bring Your Own Authentication

When you authenticate Yahoo users with Nylas’ BYO Authentication, you pass a username, password, host, port, and type during the process instead of providing a refresh token.

curl -X POST 'https://api.us.nylas.com/v3/connect/custom' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "provider": "imap",
    "settings": {
      "imap_username": "[email protected]",
      "imap_password": "<YAHOO_APP_PASSWORD>",
      "imap_host": "imap.mail.yahoo.com",
      "imap_port": 993,
      "type": "yahoo"
    }
  }'

import "dotenv/config";
import Nylas from "nylas";

const config = {
  apiKey: process.env.NYLAS_API_KEY,
  apiUri: process.env.NYLAS_API_URI,
};

const nylas = new Nylas(config);

async function auth() {
  try {
    const response = await nylas.auth.grants.create({
      requestBody: {
        provider: "imap",
        settings: {
          imap_username: process.env.YAHOO_IMAP_USERNAME,
          imap_password: process.env.YAHOO_IMAP_PASSWORD,
          imap_host: "imap.mail.yahoo.com",
          imap_port: 993,
          type: "yahoo",
        },
      },
    });

    console.log("User connected:", response);
  } catch (error) {
    console.error("Error connecting user:", error);
  }
}

auth();

from dotenv import load_dotenv
load_dotenv()

import os
import sys
from nylas import Client

nylas = Client(
    os.environ.get('NYLAS_API_KEY'),
    os.environ.get('NYLAS_API_URI')
)

# Create a grant
response = nylas.auth.custom_authentication(
  request_body={
    "provider": "imap",
    "settings": {
      "imap_host": "imap.mail.yahoo.com",
      "imap_port": 993,
      "imap_username": os.environ.get('YAHOO_IMAP_USERNAME'),
      "imap_password": os.environ.get('YAHOO_IMAP_PASSWORD'),
      "type": "yahoo"
    },
  }
)

# frozen_string_literal: true

require 'nylas'
require 'dotenv/load'
require 'sinatra'

set :show_exceptions, :after_handler

error 404 do
  'No authorization code returned from Nylas'
end

error 500 do
  'Failed to exchange authorization code for token'
end

nylas = Nylas::Client.new(api_key: ENV['NYLAS_API_KEY'])

get '/nylas/auth' do
  request_body = {
  provider: 'imap',
  settings: {
      "imap_username": "<YAHOO_USERNAME>",
      "imap_password": "<YAHOO_APP_PASSWORD>",
      "imap_host": "imap.mail.yahoo.com",
      "imap_port": 993,
      "type": "yahoo"
    }
  }

  response = nylas.auth.custom_authentication(request_body)
  "#{response}"
end

import com.nylas.NylasClient
import com.nylas.models.*
import spark.kotlin.Http
import spark.kotlin.ignite

fun main(args: Array<String>) {
  val nylas: NylasClient = NylasClient(apiKey = "<NYLAS_API_KEY>")
  val http: Http = ignite()

  http.get("/nylas/auth") {
    val settings: MutableMap<String, String> = HashMap()

    settings["imap_username"] = "<YAHOO_USERNAME>";
    settings["imap_password"] = "<YAHOO_APP_PASSWORD>";
    settings["imap_host"] = "imap.mail.yahoo.com";
    settings["imap_username"] = "imap.mail.yahoo.com";
    settings["imap_port"] = "993";
    settings["type"] = "yahoo";

    var requestBody = CreateGrantRequest(AuthProvider.IMAP, settings)
    var authData = nylas.auth().customAuthentication(requestBody);

    response.redirect(authData.toString())
  }
}

import java.util.*;
import static spark.Spark.*;
import com.nylas.NylasClient;
import com.nylas.models.*;

public class AuthRequest {
  public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
    NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();

    get("/nylas/auth", (request, response) -> {
      List<String> scope = new ArrayList<>();
      Map<String, String> settings = new HashMap<>();

      settings.put("imap_username","<YAHOO_USERNAME>");
      settings.put("imap_password","<YAHOO_APP_PASSWORD>");
      settings.put("imap_host","imap.mail.yahoo.com");
      settings.put("imap_port","993");
      settings.put("type","yahoo");

      CreateGrantRequest requestBody = new CreateGrantRequest(AuthProvider.IMAP, settings);
      Response<Grant> authData = nylas.auth().customAuthentication(requestBody);

      response.redirect(String.valueOf(authData));

      return null;
    });
  }
}

Yahoo OAuth scopes

You can only use the Nylas Email API with grants authenticated using Yahoo OAuth.

The table below lists the permissions you need to include in your Yahoo provider auth application for each endpoint.

Endpoint	Scopes
`GET /v3/grants/<NYLAS_GRANT_ID>/messages` `GET /v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID>`	`email` `mail-r`
`PUT /v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID>` `DELETE /v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID>` `POST /v3/grants/<NYLAS_GRANT_ID>/messages/smart-compose` `POST /v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID>/smart-compose` `POST /v3/grants/<NYLAS_GRANT_ID>/messages/send`	`email` `mail-r` `mail-w`

All message.* notifications require Yahoo’s email and mail-r scopes.

Yahoo provider limitations

By default, Nylas stores messages from Yahoo grants in a cache for 90 days after they’re received or created. You can access older messages by specifying "query_imap": true when you make a request to the following endpoints: Get Message, Get all Messages, Get Draft, Get all Drafts, and the Attachments endpoints. This directly queries the IMAP server instead of Nylas’ cache.

Nylas doesn’t send webhook notifications for changes to messages older than 90 days.

Yahoo rate limits

Yahoo doesn’t publicize its sending limits for messages. If you encounter a rate limit notification, you’ll need to wait until the limit expires to send messages. Usually, the duration of the limit is included in the notification. For more information, see Yahoo’s official documentation.