Yahoo authentication

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

If you are authenticating Yahoo users, you should use the new API v3 Yahoo OAuth method instead of IMAP authentication.

Authenticate Yahoo users with OAuth

⚠️ OAuth support for Yahoo is only available for Nylas API v3. If you are using Nylas v2.x, your Yahoo users must set up app passwords in Yahoo to grant Nylas access.

This section explains how to create a set up Yahoo OAuth and create a grant with it.

First you request access and set up a Yahoo provider auth application.
Create a Yahoo connector in your Nylas application.
Set up an OAuth listener in your project that can perform an OAuth handshake.
Use the information from that process to make Custom Auth requests which create grants for the users.

See the official Yahoo OAuth 2.0 Guide for more information.

Request data access from Yahoo

Create a Yahoo account that is only accessible to your organization's administrators.
Submit a Developer Access Form to Yahoo. This form 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 are using Nylas to connect.
1. Email Address: Use your admin email address.
2. API required: Select IMAP .
3. Your YDN account: Use your admin email address.
After you submit this form, Yahoo emails you a Yahoo Mail Products Commercial Access Agreement. Sign this form and email it back to Yahoo.

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

Create a Yahoo application

Go to the Yahoo Apps page and sign in with your admin Yahoo account.
Click Create an App.
Fill out the application details.
- Application Name: Enter a name for your application.
- Description: Enter a description for your application.
- Homepage URL: Enter your application's homepage URL. Can be empty.
- Redirect URI(s): You can leave this empty and add your endpoint's URL after you create a Yahoo connector for your application.
- OAuth Client Type: Select Confidential Client
- API Permissions:
  - Select Mail, and if you use Nylas to send or modify email messages select Read/Write. If you do not send or modify messages, you can select Read.
  - Select OpenID Connect Permissions, and select Email.
Click Create App.
On the next page you'll see your app's client ID and client secret. Write them down and save them to your secrets manager, because you'll need them in the next step.

Create a Yahoo connector for your Nylas application

Make sure you are using the v3 Dashboard, have a non-Sandbox Nylas v3 application, and generate an API key for that application.

Create a connector by making a POST /v3/connectors request and setting the provider to yahoo.

curl -X POST https://api.us.nylas.com/v3/connectors \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Yahoo connector for testing",
    "provider": "yahoo",
    "settings":
    {
      "client_id": "<YAHOO_CLIENT_ID>",
      "client_secret": "<YAHOO_CLIENT_SECRET>"
    },
    "scope": [
      "email",
      "mail-r",
      "mail-w" # if you want to send/modify emails
    ]
}'

Change the scopes to match what you selected in the API Permissions step when you configured your Yahoo application.

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

Create a Yahoo OAuth-client endpoint in your project. This endpoint must be able 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.

When your OAuth-client endpoint is ready, go back to the Yahoo Apps page. Sign in, find your Yahoo auth app, and add your endpoint's URL to the Redirect URIs section.

⚠️ Yahoo auth app redirect URIs: Registering a redirect URIs can take up to 24 hours. You may experience inconsistencies when trying to log in to your account during that time.

Create a Yahoo grant with Yahoo OAuth

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

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

When a user requests this URL they are redirected to Yahoo's login page. There, they log in 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 POST /v3/connect/custom request. This finishes the Yahoo OAuth flow and creates a Nylas grant.

Yahoo OAuth flow example

The OAuth flow is as follows:

Yahoo sends a GET request with code query parameter.

Your endpoint extracts the value of code from the query parameter, then makes a token request to Yahoo:

curl --location --request POST '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=<your_endpoint_url>' \
--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 then uses the refresh token to create a Nylas grant by making a POST /v3/connect/custom request.

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": "<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.

All email-related webhooks 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/`	`email` `mail-r`
PUT `/messages/` DELETE `/messages/` 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": "[email protected]",
    "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())
  }
}