Source: https://cli.nylas.com/guides/email-api-sandbox-testing

# Gmail API Sandbox: Test Email Integrations

You searched for a Gmail API sandbox or test environment and found nothing official — because Google doesn't provide one. Every Gmail API call runs against a real mailbox. This guide compares the 4 working substitutes: a dedicated test account, the Amazon SES sandbox for the sending side, fake SMTP inboxes, and CLI demo mode with sample data and zero credentials.

Written by [Pouya Sanooei](https://cli.nylas.com/authors/pouya-sanooei) Software Engineer

Updated June 6, 2026

> **TL;DR:** There is no Gmail API sandbox — every call touches a real mailbox. For exploring commands and writing docs, use [`nylas demo email list`](https://cli.nylas.com/docs/commands/demo-email-list) (sample data, no credentials). For integration tests, connect a dedicated test account (the free tier includes 5 connected accounts). For send-side testing, the Amazon SES sandbox caps you at 200 messages per 24 hours to verified addresses only.

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

## Is there a Gmail API sandbox or test environment?

No. Google does not offer a sandbox, mock tier, or test environment for the Gmail API — the [API reference](https://developers.google.com/workspace/gmail/api/reference/rest) documents exactly one surface, and it operates on real mailboxes with real OAuth grants. Anything you send goes to a real recipient; anything you delete is really gone (or in Trash for its 30-day window). Quota costs accrue against your real per-user budget of 6,000 units per minute per user on new projects.

Compare that with payments, where Stripe's [test mode](https://docs.stripe.com/test-mode) is a first-class product feature. Email never grew the equivalent, and not just at Google — Microsoft Graph likewise has no mailbox sandbox, only developer tenants with real mailboxes in them. So "sandbox" for email means picking one of 4 substitutes, each safe in a different place. The rest of this guide compares them.

## What are the 4 sandbox substitutes?

The 4 working approaches differ on one axis that matters: how close they sit to production behavior. Sample-data demo modes are perfectly safe and zero-setup but prove nothing about deliverability. A dedicated real account behaves exactly like production because it is production — scoped to an inbox nobody depends on. The table maps each option to its job.

| Option | Setup time | Best for | Doesn't test |
| --- | --- | --- | --- |
| **CLI demo mode** (sample data) | 0 minutes, no account | Learning commands, docs screenshots, demos | Auth, delivery, real data shapes at scale |
| **Dedicated test account** | ~10 minutes | Integration tests, E2E flows, spam-filter reality | Nothing — it is real; just keep secrets out of CI logs |
| **Amazon SES sandbox** | Minutes (default state) | Send-side API integration before production access | Receiving; sends limited to verified addresses |
| **Fake SMTP inbox** (Mailtrap-style) | ~5 minutes | Catching outbound mail from dev environments | Real provider behavior: spam filtering, threading, quotas |

## How does CLI demo mode work?

Demo mode runs every major command group against built-in sample data (7 sample calendar events, a sample inbox, contacts, scheduler, and notetaker) with no account, credentials, or API key. It exists for exactly the cases where a sandbox is usually requested: evaluating the tool before signing up, learning command syntax, and taking screenshots without leaking a real inbox.

```bash
# Explore email commands with sample data — no auth
nylas demo email list

# Sample calendar events
nylas demo calendar list

# The full interactive TUI, sample data only
nylas demo tui
```

The boundary is clear by design: demo mode proves your command syntax and your parsing logic, not your OAuth setup or deliverability. The moment a test needs a real provider response (pagination behavior, folder names, rate-limit headers), graduate to a test account.

## How do you set up a dedicated test account?

A dedicated test account is a real Gmail or Outlook mailbox created only for automated tests, connected once and reused across the suite. It costs nothing: a fresh Gmail address plus the free tier's 5 connected accounts covers a test matrix of multiple providers with room to spare. Because the account is real, your tests exercise the same spam filtering, threading, and quota behavior production will see.

Connect it once with OAuth, then every CLI call in the suite targets it. Total setup is about 10 minutes including the mailbox signup.

```bash
# Connect the test mailbox (browser OAuth, one time)
nylas auth login

# Verify the connection and list what's in the test inbox
nylas auth whoami
nylas email list --limit 5 --json
```

Two hygiene rules keep this safe. Never connect a mailbox a human depends on — the suite will delete and send things. And in CI, authenticate headlessly with `nylas auth config --api-key` rather than replaying browser OAuth; the [E2E testing guide](https://cli.nylas.com/guides/e2e-email-testing) shows the full CI wiring including polling patterns.

## What does the Amazon SES sandbox actually allow?

The SES sandbox is the one true sandbox in mainstream email infrastructure, and it covers only the sending side. Per the [SES developer guide](https://docs.aws.amazon.com/ses/latest/dg/request-production-access.html), AWS places "all new accounts in the Amazon SES sandbox," where "you can only send mail to verified email addresses and domains, or to the Amazon SES mailbox simulator" and "a maximum of 200 messages per 24-hour period."

That makes it a good fit for testing transactional send code (password resets, alerts) before requesting production access, and a non-answer for anything inbox-shaped: it cannot receive, list, or search mail. Teams commonly pair it with one of the other options: SES sandbox for outbound, a dedicated test account for the receiving assertions.

## When is a fake SMTP inbox the right choice?

A fake SMTP server accepts anything your app sends and shows it in a web UI, with nothing delivered to real recipients. That's ideal for development environments where dozens of accidental sends per hour are normal, and inadequate for release testing, where the question is whether Gmail actually accepts and files your message. The trade-off is structural: no real provider sits behind the inbox, so spam filtering, threading, and quota behavior go untested.

The [Mailtrap alternative guide](https://cli.nylas.com/guides/mailtrap-alternative-real-inbox-testing) works through the moment teams outgrow the fake inbox (usually the first production incident a staging environment couldn't reproduce) and how to switch the same test suite to a real-inbox backend without rewriting assertions.

## Next steps

- [E2E Email Testing with Playwright](https://cli.nylas.com/guides/e2e-email-testing) — wire the test account into browser tests with polling and link extraction
- [Mailtrap alternative: real inbox testing](https://cli.nylas.com/guides/mailtrap-alternative-real-inbox-testing) — when fake SMTP stops being enough
- [Cypress email testing](https://cli.nylas.com/guides/cypress-email-testing) — the same patterns for Cypress suites
- [Getting started](https://cli.nylas.com/guides/getting-started) — install and authenticate in under 2 minutes
- [Full command reference](https://cli.nylas.com/docs/commands) — every demo and email subcommand documented