URL: /code/integrations/gmail · Id: `page:/code/integrations/gmail`

# Gmail

> Your agents send from your own Gmail address, read every reply, and stop on any unsubscribe, with each thread filed to its lead.

Your agents send from your own Gmail address, read every reply, and stop on any unsubscribe, with each thread filed to its [lead](https://startupbuilder.dev/business/nouns/lead).

```text title="Run it · Ask"
Show me the first email my Sequence would send to Rosa at Northgate Rentals from my cold inbox.
```

```ts title="Run it · SDK"
import { $ } from 'startup-builder'

const result = await $.try.Contact.enroll({ contact: 'contacts/rosa-northgate', sequence: 'sequences/first-touch', from: 'dana@tryleaseline.app' })
```

```json title="Run it · Response"
{
  "$type": "Message",
  "mode": "try",
  "stored": false,
  "from": "Dana Okafor <dana@tryleaseline.app>",
  "to": "rosa@northgate-rentals.com",
  "subject": "The rent spreadsheet at Northgate",
  "body": "Saw you are hiring a leasing coordinator. Is the rent spreadsheet part of the job?",
  "sendAt": "2026-10-28T14:10:00Z",
  "mailbox": {
    "warmedDays": 14,
    "perDay": 30,
    "sentToday": 11
  },
  "headers": {
    "List-Unsubscribe": "present",
    "List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
  }
}
```

- **Connect:** Sign in once, 2 grants
- **Runs through:** [Your account](/code/integrations#three-ways)
- **First run:** Enroll 25 checked people in your first Sequence, free on your account
- **Sites:** [Gmail](/venues#gmail)

## Connect once
1. Call `Integration.connect` with `system: 'mailboxes'` and `venue: 'gmail'`, then open the `connectUrl` it returns and sign in as the Google account you send from.
2. Approve the two grants Google lists: send as you, and read the threads your agents start.
3. Authenticate the sending Domain once with `Domain.authenticate`, which writes SPF, DKIM and DMARC and checks them before the first send.

| Grant | What it unlocks | Scope |
| --- | --- | --- |
| Send as you | Each Sequence step, reply and broadcast leaves from your own address, in your Sent folder | `https://www.googleapis.com/auth/gmail.send` |
| Read replies | Every reply lands on its thread and its lead within a minute; the platform reads no thread your agents did not start | `https://www.googleapis.com/auth/gmail.readonly` |

| To | Do this |
| --- | --- |
| Pause | `Integration.pause` stops every call through Gmail at once and keeps the token; `Integration.resume` picks up from the same cursor. |
| Reconnect | `Integration.reconnect` returns a fresh `connectUrl` that lasts one hour, and keeps the Integration's id and cursor, so nothing imports twice. |
| Disconnect | `Integration.revoke` revokes the token with Gmail; every record it brought in stays in your records. |

## What your agents do
| Ask | Verb | Runs through | Price |
| --- | --- | --- | --- |
| Send each step of my Sequence from my own address, and stop on any reply. | [`Contact.enroll`](/code/apps/sequences/enroll) | Your account | Free |
| Hold this reply until 9:00 in their time zone, then send it. | [`Message.schedule`](/code/apps/mailboxes/schedule) | Your account | Free |
| Send the launch note to my waitlist. | [`Message.broadcast`](/code/apps/mailboxes/broadcast) | Your account | Free |
| Answer this reply in the same thread. | [`Conversation.answer`](https://startupbuilder.dev/business/nouns/conversation/answer) | Your account | Free |
| Turn the first reply into a lead, with the thread as its source. | [`Prospect.engage`](https://startupbuilder.dev/business/nouns/prospect/engage) | Your account | Free |
| Stop every send to anyone who asks. | [`Contact.unsubscribe`](https://startupbuilder.dev/business/nouns/contact/unsubscribe) | Your account | Free |

Calls on your own account are free.

## What it holds
| Noun | The account’s object | When | Which side leads |
| --- | --- | --- | --- |
| [Message](https://startupbuilder.dev/business/nouns/message) | `message` | Your agent sends a step, a reply or a broadcast | Your records |
| [Message](https://startupbuilder.dev/business/nouns/message) | `message` | A reply arrives in the inbox | The account |
| [Thread](https://startupbuilder.dev/business/nouns/thread) | `thread` | The first send opens it; every reply joins it | The account |
| [Contact](https://startupbuilder.dev/business/nouns/contact) | `From, To and Cc` | An address writes to you for the first time | Your records |

## Events and webhooks
| Direction | Event |
| --- | --- |
| Emits | `Message.created`, `Contact.enrolled`, `Message.broadcasted`, `Prospect.engaged`, `Contact.unsubscribed` |
| Hears `users.watch` | Becomes `Message.created` |

Any Event can wake a Workflow, and a Watch delivers it to your endpoint, signed ([Events and webhooks](/code/events)).

## Limits
| What | Limit | Call |
| --- | --- | --- |
| Sends from one inbox | 2,000 messages in a rolling 24 hours on a Google Workspace account, to at most 10,000 recipients; the rest wait for the window with `quota-reached` | [`Message.broadcast`](/code/apps/mailboxes/broadcast) |
| Outside recipients | 3,000 addresses outside your own domain a day, and 500 on one message | [`Message.broadcast`](/code/apps/mailboxes/broadcast) |
| Cold sends | 30 a day per inbox after 14 days of warm-up, held by your standing approval; a Sequence spreads the rest over the next days | [`Contact.enroll`](/code/apps/sequences/enroll) |
| Replies | Gmail pushes each new message within seconds; the platform renews the mailbox watch daily, inside the 7 days Gmail allows | Every call |

## Field map
| Our field | Gmail’s field | Notes | Calls |
| --- | --- | --- | --- |
| `Message.from` | `raw: From header` | Your address, or a send-as alias you set up in Gmail | [`Message.schedule`](/code/apps/mailboxes/schedule), [`Message.broadcast`](/code/apps/mailboxes/broadcast), [`Contact.enroll`](/code/apps/sequences/enroll) |
| `Message.to` | `raw: To header` | None. | [`Message.schedule`](/code/apps/mailboxes/schedule), [`Message.broadcast`](/code/apps/mailboxes/broadcast), [`Contact.enroll`](/code/apps/sequences/enroll) |
| `Message.subject` | `raw: Subject header` | A reply keeps the thread’s subject, so Gmail threads it | [`Message.schedule`](/code/apps/mailboxes/schedule), [`Message.broadcast`](/code/apps/mailboxes/broadcast), [`Contact.enroll`](/code/apps/sequences/enroll) |
| `Message.body` | `raw: text/plain and text/html parts` | None. | [`Message.schedule`](/code/apps/mailboxes/schedule), [`Message.broadcast`](/code/apps/mailboxes/broadcast), [`Contact.enroll`](/code/apps/sequences/enroll) |
| `Message.purpose` | `raw: List-Unsubscribe and List-Unsubscribe-Post headers` | A commercial purpose adds the one-click unsubscribe headers Gmail shows as a link | [`Message.broadcast`](/code/apps/mailboxes/broadcast), [`Contact.enroll`](/code/apps/sequences/enroll) |

## What try does here
Renders the exact email, headers included, and returns it with the time it would send; nothing reaches Gmail and no draft is saved.

## How long a connection lasts
A connection lasts until you revoke it in your Google Account, or until you change your Google password, which ends any grant that holds Gmail access.

The platform asks you to reconnect 7 days before it runs out; until you do, a call that needs it refuses with [`needs-reauth`](/code/refusals#needs-reauth).

## Plays and strategies
| Kind | Where |
| --- | --- |
| Plays | [Cold email](/plays/cold-email), [Warm intros](/plays/warm-intros), [lead nurture](/plays/lead-nurture), [Launch week](/plays/launch-week), [customer referrals](/plays/customer-referrals), [Owned newsletter](/plays/owned-newsletter) |
| Strategies | [Hands-on](/strategy/hands-on), [Launch and search](/strategy/launch-and-search) |

## Used by
- **Agent tasks:** [Launch day](/capabilities/earn-first-links/launch-day) · [Link pitches](/capabilities/earn-first-links/link-pitches) · [Save and win back](/capabilities/keep-and-grow/save-and-win-back) · [Answer every inbound](/capabilities/convert-visitors/answer-every-inbound) · [Personal first touch](/capabilities/reach-out/personal-first-touch)
- **Services:** [Booked first calls](/capabilities/reach-out/booked-first-calls) · [Demand generation](/capabilities/find-customers/demand-generation)

## Reference

| Call | Path | Price |
| --- | --- | --- |
| [`Contact.enroll`](/code/apps/sequences/enroll) | `POST /contacts/enroll` | Free |
| [`Message.schedule`](/code/apps/mailboxes/schedule) | `POST /messages/schedule` | Free |
| [`Message.broadcast`](/code/apps/mailboxes/broadcast) | `POST /messages/broadcast` | Free |
| [`Conversation.answer`](https://startupbuilder.dev/business/nouns/conversation/answer) | `POST /conversations/answer` | Free |
| [`Prospect.engage`](https://startupbuilder.dev/business/nouns/prospect/engage) | `POST /prospects/engage` | Free |
| [`Contact.unsubscribe`](https://startupbuilder.dev/business/nouns/contact/unsubscribe) | `POST /contacts/unsubscribe` | Free |