Google Postmaster Tools Connections

Google Postmaster Tools connections enable agents to query email deliverability metrics for domains sending to Gmail users.

Recommended: Create and manage connections via the web UI at https://ui.{deployment}.firetigerapi.com/settings/connections

Overview

Google Postmaster Tools provides insights into:

  • Domain/IP Reputation - How Gmail perceives your sending reputation
  • Spam Rates - Percentage of emails marked as spam by users
  • Authentication - SPF, DKIM, and DMARC success rates
  • Encryption - TLS usage for email transport
  • Delivery Errors - Common delivery issues and their frequency

Prerequisites

Before creating a Google Postmaster Tools connection, complete these setup steps:

1. Create a Google Cloud Project

  1. Go to Google Cloud Console
  2. Create a new project or select an existing one

2. Enable the Postmaster Tools API

  1. Go to Enable Postmaster Tools API
  2. Select your project and click Enable

3. Create a Service Account

  1. Go to Service Accounts
  2. Click Create Service Account
  3. Fill in:
    • Name: e.g., “Postmaster API Client”
    • ID: auto-generated
    • Description: “Service account for Postmaster Tools API access”
  4. Click Create and Continue, then Done

4. Enable Domain-Wide Delegation

  1. Click on the service account you created
  2. Go to the Details tab
  3. Click Show Advanced Settings
  4. Under Domain-wide delegation, click Enable Google Workspace Domain-wide Delegation
  5. Note the Client ID (a numeric ID like 123456789012345678901)

5. Download Service Account Credentials

  1. On the service account page, go to the Keys tab
  2. Click Add Key → Create new key
  3. Choose JSON format and click Create
  4. Save the downloaded JSON file securely

6. Configure Domain-Wide Delegation in Google Workspace

This step requires Google Workspace Super Admin access.

  1. Go to Google Workspace Admin Console
  2. Navigate to Security → Access and data control → API controls
  3. Scroll to Domain-wide delegation → Click Manage Domain Wide Delegation
  4. Click Add new
  5. Fill in:
    • Client ID: The numeric Client ID from step 4
    • OAuth scopes: https://www.googleapis.com/auth/postmaster.readonly
  6. Click Authorize

7. Verify Postmaster Access

The user you’ll impersonate must have access to Postmaster Tools:

  1. Go to Gmail Postmaster Tools
  2. Sign in as the user who will be impersonated
  3. Verify they can see the domains you want to query

Connection Parameters

Required Parameters

Parameter Type Description
service_account_json string The full contents of the service account JSON key file
impersonate_user string Email of a user with access to Postmaster Tools (e.g., admin@yourdomain.com)

Available Tools

Once configured, agents have access to two tools:

ListDomains

Lists all domains registered in the Postmaster Tools dashboard.

Use this to: Discover which domains are available for querying.

Returns: Domain names and permission levels (OWNER/READER).

GetTrafficStats

Retrieves daily traffic statistics for a domain.

Parameters:

  • domain (required): The domain to query (e.g., example.com)
  • start_date (optional): Start date in YYYY-MM-DD format (defaults to 7 days ago)
  • end_date (optional): End date in YYYY-MM-DD format (defaults to today)

Returns:

  • Domain reputation (HIGH, MEDIUM, LOW, BAD)
  • IP reputations with sample IPs
  • User-reported spam ratio
  • SPF/DKIM/DMARC success rates
  • Encryption ratios (inbound/outbound TLS)
  • Delivery errors by type

Description Field

Document the domains and use cases for the connection.

Example:

Google Postmaster Tools for monitoring email deliverability to Gmail.

Available domains:
- example.com - Primary marketing domain
- transactional.example.com - Transactional email domain

Use this connection to:
- Check domain/IP reputation after email campaigns
- Investigate spam complaints or delivery issues
- Monitor authentication (SPF, DKIM, DMARC) success rates
- Track encryption compliance

Note: Google requires sufficient email volume for metrics to be available.
Domains with low Gmail volume may not show statistics.

Example Connection 

{
  "display_name": "Postmaster Tools - Example Corp",
  "description": "Google Postmaster Tools for monitoring email deliverability...",
  "connection_details": {
    "google_postmaster": {
      "service_account_json": "{\"type\": \"service_account\", \"project_id\": \"your-project\", ...}",
      "impersonate_user": "admin@example.com"
    }
  }
}

Troubleshooting

“Not authorized to access this resource”

  • Verify domain-wide delegation is configured with the correct Client ID
  • Check that the scope https://www.googleapis.com/auth/postmaster.readonly is authorized
  • Ensure the impersonate_user has access to Postmaster Tools

“No domains found”

  • The impersonated user must have verified domains at https://postmaster.google.com/
  • Domain verification requires adding DNS records (follow Google’s instructions)

“No traffic statistics available”

Google requires sufficient email volume to display statistics. This can happen if:

  • The domain has low email volume to Gmail users
  • The date range has no email activity
  • The domain was recently verified

API returns 403

  • Verify the Postmaster Tools API is enabled in your Google Cloud project
  • Check that domain-wide delegation is properly configured

Best Practices

  • Use a dedicated service account - Create a separate service account for Postmaster Tools access
  • Impersonate an admin user - The impersonated user should have access to all domains you need to query
  • Monitor regularly - Set up regular checks for reputation changes or spam spikes
  • Document domains - List available domains in the description field for agent context

API Version

This integration uses the Google Postmaster Tools API v1 (stable). Future versions may add support for v2beta features including compliance status and batch queries.

This site uses Just the Docs, a documentation theme for Jekyll.