Skip to content
BuildBase

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.

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

Warning

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.

Before you start

The domain must already be a sending domain 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.

StatisticShown as
User-reported spam rateA chart by day, with lines at 0.10% and 0.30%
Domain reputationA badge: Bad, Low, Medium or High, from the newest day
SPF, DKIM and DMARC successThe 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.

MethodPathPurpose
POST/api/emails/domains/:id/postmaster/connectStart the Google sign-in; returns { url }
GET/api/emails/domains/:id/postmasterThe connection, the stored days and the warning
POST/api/emails/domains/:id/postmaster/refreshRead from Gmail now (once a minute at most)
DELETE/api/emails/domains/:id/postmasterDisconnect and give the access back
GET/api/emails/campaigns/:id/postmasterGmail'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