Source: https://cli.nylas.com/guides/oauth-scopes-for-email-explained

# OAuth Scopes for Email, Explained

A scope is the line between an app that can read your inbox and one that can also send as you. Get scopes wrong and you either can't do the work or you over-collect access a security reviewer will flag. This guide explains what OAuth scopes are, which ones email tasks actually need on Google and Microsoft, why least privilege matters, and how Nylas requests the right scopes during the connect flow so you don't hand-assemble them per provider.

Written by [Caleb Geene](https://cli.nylas.com/authors/caleb-geene) Director, Site Reliability Engineering

Updated June 8, 2026

> **TL;DR:** A scope is a named permission the user grants at consent time — read mail, send mail, manage calendar. Request the narrowest set the feature needs: read-only for triage, send for replies. Google and Microsoft name scopes differently (`gmail.readonly` vs `Mail.Read`), but the principle is identical. Nylas requests the right scopes during `nylas auth login`, so you connect once instead of assembling scope strings per provider.

Command references used in this guide: [`nylas auth login`](https://cli.nylas.com/docs/commands/auth-login), [`nylas auth whoami`](https://cli.nylas.com/docs/commands/auth-whoami), and [`nylas auth status`](https://cli.nylas.com/docs/commands/auth-status).

## What are OAuth scopes for email?

An OAuth scope is a named permission the user approves when they connect an app to their mailbox. It defines exactly what the resulting access token can do — read messages, send mail, manage labels, or touch the calendar — and nothing more. The user sees the requested scopes on the consent screen, which is why over-asking erodes trust and can fail an app review.

Scopes are the access-control layer of OAuth 2.0, the framework defined in [RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749). The token your app receives is stamped with the granted scopes, and the provider rejects any call outside them — a read-only token can't send, even if your code tries. That server-side enforcement is what makes least privilege real rather than advisory.

## Which scopes does email access need?

Match the scope to the task. Triage and search need read-only access; sending replies needs a send scope; a full assistant that files and labels needs modify access. The table maps common email tasks to the equivalent Google and Microsoft scopes, so you can see that “read the inbox” is `gmail.readonly` on Google and `Mail.Read` on Microsoft.

| Task | Google scope | Microsoft permission |
| --- | --- | --- |
| Read mail | `gmail.readonly` | `Mail.Read` |
| Send mail | `gmail.send` | `Mail.Send` |
| Modify / label | `gmail.modify` | `Mail.ReadWrite` |
| Calendar | `calendar` | `Calendars.ReadWrite` |

Google's restricted scopes like `gmail.modify` trigger a security assessment for production apps, per the [Google OAuth scopes reference](https://developers.google.com/identity/protocols/oauth2/scopes). That's a real cost reason to request read-only when read-only is enough.

## How does Nylas handle scopes for you?

Nylas requests the scopes your integration needs during the connect flow, so each user grants them in one consent screen and you never hand-build a scope string per provider. The OAuth app is configured once in the Nylas dashboard; `nylas auth login` walks the user through that consent, and the resulting grant carries the approved permissions. Switching a user from Gmail to Outlook doesn't change your code.

This removes the most error-prone part of multi-provider OAuth: keeping three providers' scope names and consent quirks in sync. You decide what the app should be able to do; Nylas maps that to each provider's scope vocabulary. The principle of least privilege still applies — request the narrowest access the feature needs, because the user sees it and a reviewer will too.

```bash
# Connect a mailbox; the user consents to the requested scopes
nylas auth login --provider google

# See which account and grant you're operating as
nylas auth whoami --json
nylas auth status
```

## How do you check what you're authorized for?

Check your active grant with `nylas auth whoami` and `nylas auth status`. They report the connected account and the state of the grant, so you can confirm you're acting as the right user before running commands. If a command fails with a permission error, the grant likely lacks the scope for that action, and the fix is to reconnect with the needed access.

When you add a capability — say you start sending after only ever reading — the user must re-consent so the grant picks up the send scope. Re-running `nylas auth login` walks them through that. Treat a scope change like any auth change: it requires fresh consent, and the old token won't silently gain new powers.

## Next steps

- [Refresh token management](https://cli.nylas.com/guides/refresh-token-management) — how tokens expire and renew
- [Email API authentication methods](https://cli.nylas.com/guides/email-api-authentication-methods) — OAuth, app passwords, and keys
- [Service account vs OAuth](https://cli.nylas.com/guides/service-account-vs-oauth-email) — app-level vs per-user access
- [Fix the invalid_grant error](https://cli.nylas.com/guides/fix-invalid-grant-error) — when a grant stops working
- [Google domain-wide delegation](https://cli.nylas.com/guides/google-domain-wide-delegation) — service-account access vs per-user scopes
- [Full command reference](https://cli.nylas.com/docs/commands) — every flag and subcommand documented