Authenticate Yahoo accounts with Nylas

Nylas supports two ways to authenticate end users who use Yahoo as their email provider: using Yahoo OAuth and Custom Authentication, or by having them create an app password then using the app password with Custom or Hosted IMAP auth.

💡 If you're using Nylas v3, Nylas strongly recommends authenticating Yahoo accounts using Yahoo's OAuth method instead of IMAP. This gives you more secure access to your end users' data.

Set up Yahoo OAuth and Nylas Custom Authentication

⚠️ Support for Yahoo OAuth is available in Nylas v3 only. If you're using Nylas v2.x, your Yahoo users must set up app passwords to grant Nylas access to their accounts. For more information about Yahoo OAuth, see Yahoo's official documentation.

If you're using Nylas v3, you can authenticate your end users with Yahoo OAuth and Nylas Custom Authentication. First, you have to set up your environment and authentication flow:

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

Request data access from Yahoo

First, request access to Yahoo data for your Nylas application:

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.
After you complete the access form, Yahoo sends you a Yahoo Mail Products Commercial Access Agreement. Review the form, sign it, and send it back to Yahoo.

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

Create an OAuth-client endpoint to handle the Yahoo OAuth flow

Next, create an OAuth-client endpoint (also called a "redirect URI") in your Nylas 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 Custom Authentication. See the Yahoo OAuth flow example for a detailed explanation of the process the endpoint must support.

Take note of your endpoint URI, because you'll use it when you create your Yahoo auth app.

Create a Yahoo provider auth app

Now it's time to create a 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 the URI for your OAuth-client endpoint. Registering a redirect URI can 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 use Nylas to send or modify email messages, select Read/Write. If you don't send or modify email messages, select Read.
  - Select OpenID connect permissions, then choose Email.
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 Storing secrets securely.

Create a Yahoo connector

Next, you'll create a Yahoo connector for your Nylas application. You need to have a non-Sandbox v3 Nylas application and its API key to create the connector.

To create the connector, make a POST /v3/connectors request that includes "provider": "yahoo", as in the following example. The scope array must match the API permissions you set in your Yahoo auth app.

Request
Response (JSON)

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-r",
      "mail-w"  # Include if you want to send/modify emails.
    ]
  }'

{
  "request_id": "1",
  "data": {
    "provider": "yahoo"
    "scope": [
      "email",
      "mail-r",
      "mail-w"
    ]
  }
}

Create a grant 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 an end user requests this URL, they're redirected to Yahoo's login page where they log in to their account and confirm that they're allowing Nylas to access their Yahoo Mail. After they authenticate, Yahoo returns a refresh token that you use to make a Custom Authentication request. This completes the Yahoo OAuth flow and creates a Nylas grant.

Example: Yahoo OAuth flow

When it's set up, 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, then 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 returns a response that contains 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 POST /v3/connect/custom request that includes the 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>"
    }
  }'

Yahoo OAuth scopes

You can only use the Nylas Email API with Yahoo OAuth. The table below lists the permissions you need to include in your Yahoo provider auth application for each endpoint.

📝 Note: All Email notifications require the Yahoo email and mail-r scopes.

Endpoint	Yahoo scopes
GET `/messages` GET `/messages/<MESSAGE_ID>` GET `/drafts` GET `/drafts/<DRAFT_ID>` GET `/folders` GET `/folders/<FOLDER_ID>` GET `/attachments/<ATTACHMENT_ID>`	`email` `mail-r`
PUT `/messages/<MESSAGE_ID>` DELETE `/messages/<MESSAGE_ID>` POST `/drafts` PUT `/drafts/<DRAFT_ID>` DELETE `/drafts/<DRAFT_ID>` POST `/messages/smart-compose` POST `/messages/<MESSAGE_ID>/smart-compose` POST `/messages/send` POST `/messages/send` (using draft) POST `/folders` PUT `/folders/<FOLDER_ID>` DELETE `/folders/<FOLDER_ID>`	`email` `mail-r` `mail-w`

Authenticate Yahoo users with an app password

If you are using Nylas v2.x, or aren't able to set up a Yahoo OAuth application, there are two ways to authenticate Yahoo users. You can either authenticate using Hosted IMAP and the app password, or authenticate using Custom auth and the app password (called "Native auth" in v2.x).

In both of these methods the user must first create an app password.

The user creates a Yahoo app password

If your Yahoo users authenticate over IMAP, they need to authenticate using an app password instead of their email password.

To generate an app password, the end user must:

Sign in to Yahoo Mail.
Navigate to Account Info.
Go to the Account security settings.
At the bottom of the page, choose the option to Generate app password or Manage app passwords.
Generate a new app password.
Use the new password to authenticate with Nylas.

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 for Yahoo users with app password and Custom auth

When you use IMAP hosted auth you pass a username, password, host, port, and type during the Custom auth process instead of providing a refresh token. The example below shows a sample POST /v3/connect/custom request.

If you are using Nylas v2.x, use the v2.x Native authentication schema instead.

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": "john.doe@yahoo.com",
    "imap_password": "super-secret-app-password",
    "imap_host": "imap.mail.yahoo.com",
    "imap_port": 993,
    "type": "yahoo"
  }
}'

You can also use the Nylas SDKs to start the Custom auth process.

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_IMAP_USERNAME>",
          "imap_password": "<YAHOO_IMAP_PASSWORD>",
          "imap_host": "imap.mail.yahoo.com",
          "imap_port": 993,
          "type": "yahoo"
        }
  }

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

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_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;
    });
  }
}

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_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())
  }
}

Yahoo provider limitations

In Nylas v3, Yahoo and IMAP providers can retrieve email data up to 90 days old. For most providers, email webhook notifications are in real-time, however Yahoo accounts can take 5 minutes to deliver email webhooks. Nylas doesn't send webhook notifications for changes to email messages (for example folder or label changes) if the message being changed is older than 90 days.

Yahoo rate limits

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