Guide

How to List Gmail Emails from the Command Line

The Gmail API requires OAuth client setup, service account configuration, and Python or Node client libraries just to list your own inbox. The Nylas CLI handles OAuth2 and provider abstraction behind the scenes — authenticate once, then list, search, and read emails with a single command. Also works with Outlook, Exchange, Yahoo, iCloud, and IMAP.

Written by Caleb Geene Director, Site Reliability Engineering

Reviewed by Nick Barraclough

Verified — CLI 3.1.1 · Gmail · last tested April 11, 2026

Why the Gmail API is overkill for reading your inbox

Gmail has 1.8 billion active users, according to Google's 2024 earnings call. It's the most popular email provider in the world, yet listing your own messages programmatically requires a GCP project, an enabled Gmail API, and an OAuth consent screen that can take 1-6 weeks for Google to review if your app is external.

Google's Python quickstart for the Gmail API is 47 lines of code before you list a single message. The API returns message bodies as base64url-encoded MIME, so you also need to decode and parse them yourself. According to Google's Gmail API usage limits documentation, messages.list costs 5 quota units and messages.get costs another 5 — with a cap of 250 units per second per user.

The gcloud CLI doesn't have email commands. Tools like fetchmail or offlineimap sync messages locally but don't give you a way to search or filter from the terminal.

1. Install the Nylas CLI

brew install nylas/nylas-cli/nylas

See the getting started guide for all install methods including shell script, PowerShell, and Go.

2. Connect your Gmail account

Head to dashboard-v3.nylas.com, create an application, and connect your Gmail account. Then grab your API key:

nylas auth config
# Paste your API key when prompted

# Verify the connection
nylas auth whoami
# => Authenticated as you@gmail.com (Google)

3. List your emails

nylas email list              # recent emails
nylas email list --limit 10   # cap results
nylas email list --unread     # unread only

Gmail's API requires separate query parameters for sender, date, and keyword filters. The CLI uses a single search syntax that maps to Gmail's native search operators:

nylas email search "invoice" --limit 5
nylas email search "from:boss@company.com"
nylas email search "after:2026-01-01 before:2026-02-01"

5. Read a specific email

With the Gmail API, reading a message body means a separate messages.get call plus base64url decoding. The CLI handles that in one command:

nylas email read msg_abc123          # decoded body
nylas email read msg_abc123 --mime   # raw MIME source

6. JSON output for scripting

Add --json to any command and pipe into jq or a script:

nylas email list --unread --json | jq length
nylas email list --limit 5 --json | jq '.[].subject'

Quick inbox summary script:

#!/bin/bash
unread=$(nylas email list --unread --json | jq length)
echo "Unread emails: $unread"

nylas email list --unread --json \
  | jq -r '.[] | "\(.from[0].email): \(.subject)"' \
  | head -5

7. Work with Gmail labels

Gmail uses labels instead of traditional folders. The Nylas CLI maps Gmail labels to folders, so you can filter by label:

# List emails in a specific label
nylas email list --folder "INBOX"
nylas email list --folder "IMPORTANT"
nylas email list --folder "STARRED"

# List all available labels/folders
nylas email folders list

# Filter promotions and social
nylas email list --folder "CATEGORY_PROMOTIONS" --limit 5
nylas email list --folder "CATEGORY_SOCIAL" --limit 5

8. Gmail API vs Nylas CLI

The Gmail API Python quickstart needs 47 lines of code and 5 setup steps before you can list messages. Here's how the two approaches compare end to end:

StepGmail APINylas CLI
Project setupCreate GCP project, enable Gmail APINot required
OAuth consentConfigure screen, scopes, redirect URIs (1-6 week review for external apps)Handled by Nylas dashboard
CredentialsDownload JSON, manage refresh tokensnylas auth config
Code47+ lines (Python quickstart)Zero code
List emailsservice.users().messages().list() — returns IDs onlynylas email list — returns full messages
Read bodySeparate messages().get() + base64url decode (5 more quota units)nylas email read
Quota250 units/sec/user; list + get = 10 units per messageNo client-side quota management

9. Google Workspace accounts

The Nylas CLI works with both personal Gmail accounts and Google Workspace (formerly G Suite) accounts. For Workspace accounts:

  • Domain-wide delegation is not required — users authenticate with their own credentials
  • Admin consent may be required if your Workspace admin restricts third-party app access
  • Service accounts are not needed — the CLI uses standard OAuth2 user consent

If your Workspace admin has restricted third-party access, ask them to allow the Nylas application in the Google Admin console under Security → API controls → App access control.

Next steps