# Connect Gmail Postmaster Tools

See Gmail's own spam rate, reputation and authentication results for each sending domain, next to your campaign reports.

Gmail reports its own view of a sending domain in Postmaster Tools: the share of
its mail that Gmail users mark as spam, the domain's reputation, and how much of
it passes SPF, DKIM and DMARC. Connect a sending domain once and the console
reads that data every day and shows it on the domain and in each campaign
report, beside the Gmail row.

```bash
# Read what is stored for a connected domain
curl https://api.console.buildbase.app/api/emails/domains/$DOMAIN_ID/postmaster \
  -H "Authorization: $BUILDBASE_TOKEN"
```

> **Note:**
  **Pending Google's review.** Reading Postmaster Tools data needs Google to
  approve BuildBase's access, and that review is still under way. It is
  available once it has been enabled for your workspace. Until then, only Google
  accounts added as testers can connect, and Google shows them a screen saying
  the app is not verified yet. Where it is not enabled, **Connect Gmail
  Postmaster** answers "Google sign-in is not configured on this server." and
  nothing is connected.

> **Note:**
  The domain must already be a [sending domain](/email/sending-domains) in
  BuildBase, and verified in Postmaster Tools with a Google account you can sign
  in with.

## Connect a domain

1. At postmaster.google.com, add the sending domain (or its parent, such as
   `example.com` for `mail.example.com`) with a Google account, and publish the
   TXT record Google gives you to verify it.
2. In the console, open **Messaging** > **Sender accounts**, then the
   **Domains** tab, and open
   the domain. Press **Connect Gmail Postmaster** in its **Gmail Postmaster
   Tools** section.
3. Sign in with the same Google account and leave the Postmaster Tools
   permission ticked.

The console comes back with **Gmail Postmaster connected** and starts the first
read straight away. If the permission was unticked, the sign-in was cancelled or
it took too long, it says so and nothing is connected.

The access is read-only: it never changes anything in Postmaster Tools and gives
no access to mail.

## What is read

Once a day, at 07:17 UTC, BuildBase reads the last
30 days of Gmail's daily
traffic statistics for every connected domain, so a day missed to an outage is
filled by the next run. Each day is kept for
120 days.

| Statistic                   | Shown as                                               |
| --------------------------- | ------------------------------------------------------ |
| User-reported spam rate     | A chart by day, with lines at 0.10% and 0.30%          |
| Domain reputation           | A badge: Bad, Low, Medium or High, from the newest day |
| SPF, DKIM and DMARC success | The share that passed each check on the newest day     |

**Fetch now** reads a domain on demand, at most once a minute per domain.

Gmail shows data only for a domain that sends a few hundred messages a day to
Gmail users, and each day arrives a day or two late. It is a trend to watch,
not an alarm, and it never stops a send.

## Where it shows

- **On the domain.** The **Gmail Postmaster Tools** section of the domain in
  **Messaging** > **Sender accounts**, **Domains** tab, below its DNS records: the connection, the
  Google account it reads as, the last read, the reputation badge, the spam rate
  chart and the authentication results.
- **In campaign analytics.** The Gmail row of a campaign's report carries Gmail's
  spam rate for the sending domain on the days the campaign went out, up to
  seven days. A domain that is not connected shows a prompt to connect it.

## The spam rate banner

Gmail asks bulk senders to keep the user-reported spam rate under 0.10%, and from
0.30% it starts rejecting or junking their mail. When the newest day Gmail
reported is over 0.10%, a warning banner appears on the domain and on the
campaign report. At 0.30% or more it turns into an error that suggests pausing
bulk sends from the domain until the rate falls.

The banner is a warning only. Nothing is blocked, because the data is a day or
two late.

## Disconnecting and lost access

**Disconnect** stops the daily read and gives the access back to Google. The
days already read stay until they expire.

If Google stops accepting the connection, because the access was removed in the
Google account or its password changed, the domain shows **Access removed** and
the daily read skips it until you press **Reconnect**.

## Endpoints

Reading needs read access to email domains, connecting and fetching need create,
and disconnecting needs delete.

| Method   | Path                                         | Purpose                                         |
| -------- | -------------------------------------------- | ----------------------------------------------- |
| `POST`   | `/api/emails/domains/:id/postmaster/connect` | Start the Google sign-in; returns `{ url }`     |
| `GET`    | `/api/emails/domains/:id/postmaster`         | The connection, the stored days and the warning |
| `POST`   | `/api/emails/domains/:id/postmaster/refresh` | Read from Gmail now (once a minute at most)     |
| `DELETE` | `/api/emails/domains/:id/postmaster`         | Disconnect and give the access back             |
| `GET`    | `/api/emails/campaigns/:id/postmaster`       | Gmail's data for the days a campaign went out   |

`GET .../postmaster` takes `days` (1 to 120) to read a shorter or longer window.
`refresh` answers `409` for a domain that is not connected and `429` within a
minute of the last refresh.

## Next Steps

- [Sending domains](/email/sending-domains) - add and verify the domain first.
- [Campaigns overview](/email/overview) - delivery history per recipient.
- [Deliverability](/email/deliverability) - the limits that pause a campaign before Gmail acts.