GMail Postmaster

Gmail Postmaster Tools is a comprehensive email deliverability platform that provides domain reputation monitoring, spam analysis, and delivery insights for email senders, helping organizations optimize their email campaigns and maintain high deliverability rates across Gmail and Google Workspace.

Power end-to-end data operations for your GMail Postmaster API with Nexla. Our bi-directional GMail Postmaster connector is purpose-built for GMail Postmaster, making it simple to ingest data, sync it across systems, and deliver it anywhere — all with no coding required. Nexla turns API-sourced data into ready-to-use, reusable data products and makes it easy to send data to GMail Postmaster or any other destination. With comprehensive monitoring, lineage tracking, and access controls, Nexla keeps your GMail Postmaster workflows fast, secure, and fully governed.

Features

Type: API

SourceDestination

• Seamless API Integration: Connect to any endpoint as source or destination without coding, with automatic data product creation
• Visual Composition & Chaining: Build complex integrations using visual templates, chain API calls, and compose workflows with data validation and filtering
• API Proxy: Expose curated slices of your data securely with a secure and customizable API proxy that validates and transforms data on the fly
• Request optimization with intelligent batching, retry, and caching to minimize API calls and costs

Prerequisites

Before creating a Gmail Postmaster credential, you need a Google account with access to Gmail Postmaster Tools. Nexla uses its own registered OAuth2 application to authenticate with the Gmail Postmaster API, so no Google Cloud Console setup is required on your part — you only need to sign in with your Google account and grant access during the authorization flow described below. The default access scope is https://www.googleapis.com/auth/postmaster.readonly, which provides read-only access to your Gmail Postmaster data. For detailed information about the Gmail Postmaster API and OAuth2 authentication, refer to the Gmail Postmaster API documentation.

Authenticate

Create a credential in Nexla

1. After selecting the data source/destination type, click the Add Credential tile to open the Add New Credential overlay.

New Credential Overlay – Gmail Postmaster

2. Enter a name for the credential in the Credential Name field and a short, meaningful description in the Credential Description field.

Gmail Postmaster uses OAuth2 authentication to securely access the Gmail Postmaster API. OAuth2 is an industry-standard authorization protocol that allows applications to access user data without requiring users to share their passwords.

3. Click the Authorize button to begin the OAuth2 authorization flow. This will redirect you to Google's authorization page where you will be asked to sign in with your Google account and grant permissions to Nexla to access your Gmail Postmaster data.

   During the OAuth2 authorization flow, you will be redirected to Google's authorization page. You must sign in with a Google account that has access to the Gmail Postmaster Tools you want to connect. After signing in, you will be asked to grant permissions to Nexla to access your Gmail Postmaster data. The required scope is https://www.googleapis.com/auth/postmaster.readonly, which provides read-only access to your Gmail Postmaster data. Once you grant permissions, you will be redirected back to Nexla, and the authorization will be completed automatically.

4. After completing the OAuth2 authorization flow, Nexla will automatically obtain and store the access token and refresh token needed to authenticate API requests. The access token is used to authenticate each API request, and the refresh token is used to obtain new access tokens when the current access token expires.

   OAuth2 access tokens expire after a certain period for security reasons. Nexla automatically refreshes expired access tokens using the refresh token, so you typically do not need to re-authorize unless you revoke access or the refresh token expires. The access token is sent in the Authorization header with the Bearer prefix for all API requests to the Gmail Postmaster API. For detailed information about OAuth2 authentication and token management, see the Gmail Postmaster API documentation.

5. Click the Save button at the bottom of the overlay. The newly added credential will now appear in a tile on the Authenticate screen during data source/destination creation.

Use as a data source

To create a new data flow, navigate to the Integrate section, and click the New Data Flow button. Select the Gmail Postmaster connector tile, then select the credential that will be used to connect to the Gmail Postmaster account, and click Next; or, create a new Gmail Postmaster credential for use in this flow.

Endpoint templates

Nexla provides pre-built templates that can be used to rapidly configure data sources to ingest data from common Gmail Postmaster endpoints. Select the endpoint from which this source will fetch data from the Endpoint pulldown menu. Available endpoint templates are listed in the expandable boxes below. Click on an endpoint to see more information about it and how to configure your data source for this endpoint.

Get All Domains

Lists the domains that have been registered by the client.

• This endpoint automatically retrieves all domains registered in your Gmail Postmaster account. No additional configuration is required beyond selecting this endpoint template.
• The endpoint uses GET requests to https://gmailpostmastertools.googleapis.com/v1beta1/domains. The endpoint URL is automatically constructed based on the Gmail Postmaster API base URL.
• The endpoint uses token-based pagination (iteration.type: paging.next.token) through the nextPageToken mechanism. The response data path is $.domains[*], which extracts all items from the domains array in the API response.

This endpoint retrieves all domains that have been registered in your Gmail Postmaster account. The endpoint supports pagination through the nextPageToken parameter, which allows you to retrieve large lists of domains efficiently. The response includes a nextPageToken field when more results are available, and Nexla automatically handles fetching additional pages. For detailed information about the API response format and available fields, see the Gmail Postmaster API documentation.

Get One Domain

Gets a specific domain registered by the client. Returns NOT_FOUND if the domain does not exist.

• Enter the domain name you want to fetch information for in the Domain Name field. This should be the full domain name (e.g., example.com) that has been registered in your Gmail Postmaster account.
• The endpoint uses GET requests to https://gmailpostmastertools.googleapis.com/v1beta1/domains/{domain_name} where {domain_name} is the Domain Name you provide. The endpoint URL is automatically constructed based on the Gmail Postmaster API base URL and the domain name.
• The endpoint does not use pagination (iteration.type: static.url) and returns a single response. The response data path is $, which extracts the entire root-level object from the API response.

This endpoint retrieves detailed information about a specific domain registered in your Gmail Postmaster account. The domain must be registered in your account for this endpoint to return data. If the domain is not found, the API will return a NOT_FOUND error. For detailed information about the API response format and available fields, see the Gmail Postmaster API documentation.

Get Stats for A Day

Get traffic statistics for a domain on a specific date. Returns PERMISSION_DENIED if user does not have permission to access TrafficStats for the domain.

• Enter the domain name you want to fetch traffic statistics for in the Domain Name field. This should be the full domain name (e.g., example.com) that has been registered in your Gmail Postmaster account.
• Enter the date for which you want to fetch traffic statistics in the Date (yyyyMMdd format) field. The date must be in yyyyMMdd format (e.g., 20240101 for January 1, 2024). You can also use Nexla macros like {now}, {now - 1}, etc. The default value is {now} if not specified.
• The endpoint uses GET requests to https://gmailpostmastertools.googleapis.com/v1beta1/domains/{domain_name}/trafficStats/{for_date} where {domain_name} is the Domain Name you provide and {for_date} is the Date formatted as yyyyMMdd. The endpoint URL is automatically constructed based on the Gmail Postmaster API base URL, the domain name, and the date.
• The endpoint does not use pagination (iteration.type: static.url) and returns a single response. The response data path is $, which extracts the entire root-level object from the API response.

This endpoint retrieves traffic statistics for a specific domain on a specific date. The date must be in yyyyMMdd format (e.g., 20240101 for January 1, 2024). You can use Nexla macros like {now} for the current date or {now - 1} for yesterday's date. The domain must be registered in your Gmail Postmaster account, and you must have permission to access TrafficStats for the domain. If you do not have permission, the API will return a PERMISSION_DENIED error. For detailed information about the API response format and available fields, see the Gmail Postmaster API documentation.

List All Stats for Domain

List traffic statistics for all available days. Returns PERMISSION_DENIED if user does not have permission to access TrafficStats for the domain.

• Enter the domain name you want to fetch traffic statistics for in the Domain Name field. This should be the full domain name (e.g., example.com) that has been registered in your Gmail Postmaster account.
• The endpoint uses GET requests to https://gmailpostmastertools.googleapis.com/v1beta1/domains/{domain_name}/trafficStats where {domain_name} is the Domain Name you provide. The endpoint URL is automatically constructed based on the Gmail Postmaster API base URL and the domain name.
• The endpoint uses token-based pagination (iteration.type: paging.next.token) through the nextPageToken mechanism. The response data path is $.trafficStats[*], which extracts all items from the trafficStats array in the API response.

This endpoint retrieves traffic statistics for all available days for a specific domain. The domain must be registered in your Gmail Postmaster account, and you must have permission to access TrafficStats for the domain. If you do not have permission, the API will return a PERMISSION_DENIED error. The endpoint supports pagination through the nextPageToken parameter, which allows you to retrieve large lists of traffic statistics efficiently. The response includes a nextPageToken field when more results are available, and Nexla automatically handles fetching additional pages. For detailed information about the API response format and available fields, see the Gmail Postmaster API documentation.

Once the selected endpoint template has been configured, click the Test button to the right of the endpoint selection menu to retrieve a sample of the data that will be fetched. Sample data will be displayed in the Endpoint Test Result panel on the right, allowing you to verify that the source is configured correctly before saving.

Manual configuration

Gmail Postmaster data sources can also be manually configured to ingest data from any valid Gmail Postmaster API endpoint, including endpoints not covered by the pre-built templates, chained API calls, or custom request parameters. Select the Advanced tab at the top of the configuration screen, and follow the instructions in Connect to Any API to configure the API method, endpoint URL, date/time and lookup macros, path to data, metadata, and request headers.

Gmail Postmaster API endpoints typically follow the pattern https://gmailpostmastertools.googleapis.com/v1beta1/{endpoint_path} and return data in JSON format. The endpoint requires OAuth2 authentication via the Authorization: Bearer {token} header, which is handled automatically by your credential configuration. For detailed information about Gmail Postmaster API endpoints and available APIs, see the Gmail Postmaster API documentation.

Once all of the relevant settings have been configured, click the Create button in the upper right corner of the screen to save and create the new Gmail Postmaster data source. Nexla will now begin ingesting data from the configured endpoint and will organize any data that it finds into one or more Nexsets.