{
  "canonicalName": "Postmaster Tools",
  "revision": "20230907",
  "id": "gmailpostmastertools:v1beta1",
  "basePath": "",
  "fullyEncodeReservedExpansion": true,
  "name": "gmailpostmastertools",
  "schemas": {
    "Domain": {
      "properties": {
        "createTime": {
          "description": "Timestamp when the user registered this domain. Assigned by the server.",
          "type": "string",
          "format": "google-datetime"
        },
        "name": {
          "description": "The resource name of the Domain. Domain names have the form `domains/{domain_name}`, where domain_name is the fully qualified domain name (i.e., mymail.mydomain.com).",
          "type": "string"
        },
        "permission": {
          "description": "User’s permission for this domain. Assigned by the server.",
          "type": "string",
          "enum": [
            "PERMISSION_UNSPECIFIED",
            "OWNER",
            "READER",
            "NONE"
          ],
          "enumDescriptions": [
            "The default value and should never be used explicitly.",
            "User has read access to the domain and can share access with others.",
            "User has read access to the domain.",
            "User doesn't have permission to access information about the domain. User did not verify ownership of domain nor was access granted by other domain owners."
          ]
        }
      },
      "description": "A registered domain resource in the Postmaster API.",
      "id": "Domain",
      "type": "object"
    },
    "IpReputation": {
      "properties": {
        "reputation": {
          "enum": [
            "REPUTATION_CATEGORY_UNSPECIFIED",
            "HIGH",
            "MEDIUM",
            "LOW",
            "BAD"
          ],
          "description": "The reputation category this IP reputation represents.",
          "type": "string",
          "enumDescriptions": [
            "The default value which should never be used explicitly. This represents the state where no reputation information is available.",
            "Has a good track record of a very low spam rate, and complies with Gmail's sender guidelines. Mail will rarely be marked by the spam filter.",
            "Known to send good mail, but is prone to sending a low volume of spam intermittently. Most of the email from this entity will have a fair deliverability rate, except when there is a notable increase in spam levels.",
            "Known to send a considerable volume of spam regularly, and mail from this sender will likely be marked as spam.",
            "History of sending an enormously high volume of spam. Mail coming from this entity will almost always be rejected at SMTP level or marked as spam."
          ]
        },
        "ipCount": {
          "type": "string",
          "format": "int64",
          "description": "Total number of unique IPs in this reputation category. This metric only pertains to traffic that passed [SPF](http://www.openspf.org/) or [DKIM](http://www.dkim.org/)."
        },
        "numIps": {
          "format": "int64",
          "deprecated": true,
          "type": "string",
          "description": "Total number of unique IPs in this reputation category. This metric only pertains to traffic that passed [SPF](http://www.openspf.org/) or [DKIM](http://www.dkim.org/). Deprecated to be complied with ApiLinter for Quantities. Use ip_count instead."
        },
        "sampleIps": {
          "items": {
            "type": "string"
          },
          "type": "array",
          "description": "A sample of IPs in this reputation category."
        }
      },
      "id": "IpReputation",
      "type": "object",
      "description": "IP Reputation information for a set of IPs in a specific reputation category."
    },
    "TrafficStats": {
      "properties": {
        "deliveryErrors": {
          "description": "Delivery errors for the domain. This metric only pertains to traffic that passed [SPF](http://www.openspf.org/) or [DKIM](http://www.dkim.org/).",
          "type": "array",
          "items": {
            "$ref": "DeliveryError"
          }
        },
        "dmarcSuccessRatio": {
          "format": "double",
          "description": "The ratio of mail that passed [DMARC](https://dmarc.org/) alignment checks vs all mail received from the domain that successfully authenticated with either of [SPF](http://www.openspf.org/) or [DKIM](http://www.dkim.org/).",
          "type": "number"
        },
        "userReportedSpamRatioLowerBound": {
          "description": "The lower bound of the confidence interval for the user reported spam ratio. If this field is set, then the value of userReportedSpamRatio is set to the midpoint of this interval and is thus inexact. However, the true ratio is guaranteed to be in between this lower bound and the corresponding upper bound 95% of the time. This metric only pertains to emails authenticated by [DKIM](http://www.dkim.org/).",
          "format": "double",
          "type": "number"
        },
        "userReportedSpamRatioUpperBound": {
          "description": "The upper bound of the confidence interval for the user reported spam ratio. If this field is set, then the value of userReportedSpamRatio is set to the midpoint of this interval and is thus inexact. However, the true ratio is guaranteed to be in between this upper bound and the corresponding lower bound 95% of the time. This metric only pertains to emails authenticated by [DKIM](http://www.dkim.org/).",
          "format": "double",
          "type": "number"
        },
        "spfSuccessRatio": {
          "format": "double",
          "description": "The ratio of mail that successfully authenticated with SPF vs. all mail that attempted to authenticate with [SPF](http://www.openspf.org/). Spoofed mail is excluded.",
          "type": "number"
        },
        "name": {
          "type": "string",
          "description": "The resource name of the traffic statistics. Traffic statistic names have the form `domains/{domain}/trafficStats/{date}`, where domain_name is the fully qualified domain name (i.e., mymail.mydomain.com) of the domain this traffic statistics pertains to and date is the date in yyyymmdd format that these statistics corresponds to. For example: domains/mymail.mydomain.com/trafficStats/20160807"
        },
        "ipReputations": {
          "description": "Reputation information pertaining to the IP addresses of the email servers for the domain. There is exactly one entry for each reputation category except REPUTATION_CATEGORY_UNSPECIFIED.",
          "items": {
            "$ref": "IpReputation"
          },
          "type": "array"
        },
        "dkimSuccessRatio": {
          "type": "number",
          "format": "double",
          "description": "The ratio of mail that successfully authenticated with DKIM vs. all mail that attempted to authenticate with [DKIM](http://www.dkim.org/). Spoofed mail is excluded."
        },
        "outboundEncryptionRatio": {
          "format": "double",
          "description": "The ratio of outgoing mail (from Gmail) that was accepted over secure transport (TLS).",
          "type": "number"
        },
        "userReportedSpamRatio": {
          "type": "number",
          "format": "double",
          "description": "The ratio of user-report spam vs. email that was sent to the inbox. This is potentially inexact -- users may want to refer to the description of the interval fields userReportedSpamRatioLowerBound and userReportedSpamRatioUpperBound for more explicit accuracy guarantees. This metric only pertains to emails authenticated by [DKIM](http://www.dkim.org/)."
        },
        "domainReputation": {
          "type": "string",
          "enum": [
            "REPUTATION_CATEGORY_UNSPECIFIED",
            "HIGH",
            "MEDIUM",
            "LOW",
            "BAD"
          ],
          "enumDescriptions": [
            "The default value which should never be used explicitly. This represents the state where no reputation information is available.",
            "Has a good track record of a very low spam rate, and complies with Gmail's sender guidelines. Mail will rarely be marked by the spam filter.",
            "Known to send good mail, but is prone to sending a low volume of spam intermittently. Most of the email from this entity will have a fair deliverability rate, except when there is a notable increase in spam levels.",
            "Known to send a considerable volume of spam regularly, and mail from this sender will likely be marked as spam.",
            "History of sending an enormously high volume of spam. Mail coming from this entity will almost always be rejected at SMTP level or marked as spam."
          ],
          "description": "Reputation of the domain."
        },
        "spammyFeedbackLoops": {
          "type": "array",
          "description": "Spammy [Feedback loop identifiers] (https://support.google.com/mail/answer/6254652) with their individual spam rates. This metric only pertains to traffic that is authenticated by [DKIM](http://www.dkim.org/).",
          "items": {
            "$ref": "FeedbackLoop"
          }
        },
        "inboundEncryptionRatio": {
          "description": "The ratio of incoming mail (to Gmail), that passed secure transport (TLS) vs all mail received from that domain. This metric only pertains to traffic that passed [SPF](http://www.openspf.org/) or [DKIM](http://www.dkim.org/).",
          "format": "double",
          "type": "number"
        }
      },
      "description": "Email traffic statistics pertaining to a specific date.",
      "type": "object",
      "id": "TrafficStats"
    },
    "ListDomainsResponse": {
      "description": "Response message for ListDomains.",
      "id": "ListDomainsResponse",
      "type": "object",
      "properties": {
        "domains": {
          "type": "array",
          "items": {
            "$ref": "Domain"
          },
          "description": "The list of domains."
        },
        "nextPageToken": {
          "description": "Token to retrieve the next page of results, or empty if there are no more results in the list.",
          "type": "string"
        }
      }
    },
    "ListTrafficStatsResponse": {
      "id": "ListTrafficStatsResponse",
      "type": "object",
      "description": "Response message for ListTrafficStats.",
      "properties": {
        "nextPageToken": {
          "description": "Token to retrieve the next page of results, or empty if there are no more results in the list.",
          "type": "string"
        },
        "trafficStats": {
          "items": {
            "$ref": "TrafficStats"
          },
          "type": "array",
          "description": "The list of TrafficStats."
        }
      }
    },
    "FeedbackLoop": {
      "properties": {
        "spamRatio": {
          "type": "number",
          "format": "double",
          "description": "The ratio of user marked spam messages with the identifier vs the total number of inboxed messages with that identifier."
        },
        "id": {
          "type": "string",
          "description": "Feedback loop identifier that uniquely identifies individual campaigns."
        }
      },
      "id": "FeedbackLoop",
      "type": "object",
      "description": "[Feedback loop](https://support.google.com/mail/answer/6254652) identifier information."
    },
    "DeliveryError": {
      "id": "DeliveryError",
      "properties": {
        "errorClass": {
          "type": "string",
          "description": "The class of delivery error.",
          "enumDescriptions": [
            "The default value which should never be used explicitly.",
            "Delivery of message has been rejected.",
            "Temporary failure of message delivery to the recipient."
          ],
          "enum": [
            "DELIVERY_ERROR_CLASS_UNSPECIFIED",
            "PERMANENT_ERROR",
            "TEMPORARY_ERROR"
          ]
        },
        "errorRatio": {
          "type": "number",
          "format": "double",
          "description": "The ratio of messages where the error occurred vs all authenticated traffic."
        },
        "errorType": {
          "enumDescriptions": [
            "The default value which should never be used explicitly.",
            "The Domain or IP is sending traffic at a suspiciously high rate, due to which temporary rate limits have been imposed. The limit will be lifted when Gmail is confident enough of the nature of the traffic.",
            "The traffic is suspected to be spam, by Gmail, for various reasons.",
            "The traffic is suspected to be spammy, specific to the content.",
            "Traffic contains attachments not supported by Gmail.",
            "The sender domain has set up a DMARC rejection policy.",
            "The IP reputation of the sending IP is very low.",
            "The Domain reputation of the sending domain is very low.",
            "The IP is listed in one or more public [Real-time Blackhole Lists](http://en.wikipedia.org/wiki/DNSBL). Work with the RBL to get your IP delisted.",
            "The Domain is listed in one or more public [Real-time Blackhole Lists](http://en.wikipedia.org/wiki/DNSBL). Work with the RBL to get your domain delisted.",
            "The sending IP is missing a [PTR record](https://support.google.com/domains/answer/3251147#ptr)."
          ],
          "description": "The type of delivery error.",
          "type": "string",
          "enum": [
            "DELIVERY_ERROR_TYPE_UNSPECIFIED",
            "RATE_LIMIT_EXCEEDED",
            "SUSPECTED_SPAM",
            "CONTENT_SPAMMY",
            "BAD_ATTACHMENT",
            "BAD_DMARC_POLICY",
            "LOW_IP_REPUTATION",
            "LOW_DOMAIN_REPUTATION",
            "IP_IN_RBL",
            "DOMAIN_IN_RBL",
            "BAD_PTR_RECORD"
          ]
        }
      },
      "type": "object",
      "description": "Metric on a particular delivery error type."
    }
  },
  "ownerDomain": "google.com",
  "version": "v1beta1",
  "parameters": {
    "prettyPrint": {
      "location": "query",
      "type": "boolean",
      "default": "true",
      "description": "Returns response with indentations and line breaks."
    },
    "fields": {
      "description": "Selector specifying which fields to include in a partial response.",
      "location": "query",
      "type": "string"
    },
    "oauth_token": {
      "type": "string",
      "description": "OAuth 2.0 token for the current user.",
      "location": "query"
    },
    "alt": {
      "enumDescriptions": [
        "Responses with Content-Type of application/json",
        "Media download with context-dependent Content-Type",
        "Responses with Content-Type of application/x-protobuf"
      ],
      "description": "Data format for response.",
      "default": "json",
      "enum": [
        "json",
        "media",
        "proto"
      ],
      "location": "query",
      "type": "string"
    },
    "upload_protocol": {
      "description": "Upload protocol for media (e.g. \"raw\", \"multipart\").",
      "type": "string",
      "location": "query"
    },
    "callback": {
      "description": "JSONP",
      "location": "query",
      "type": "string"
    },
    "$.xgafv": {
      "location": "query",
      "type": "string",
      "enum": [
        "1",
        "2"
      ],
      "description": "V1 error format.",
      "enumDescriptions": [
        "v1 error format",
        "v2 error format"
      ]
    },
    "key": {
      "description": "API key. Your API key identifies your project and provides you with API access, quota, and reports. Required unless you provide an OAuth 2.0 token.",
      "location": "query",
      "type": "string"
    },
    "access_token": {
      "location": "query",
      "description": "OAuth access token.",
      "type": "string"
    },
    "quotaUser": {
      "description": "Available to use for quota purposes for server-side applications. Can be any arbitrary string assigned to a user, but should not exceed 40 characters.",
      "type": "string",
      "location": "query"
    },
    "uploadType": {
      "type": "string",
      "description": "Legacy upload protocol for media (e.g. \"media\", \"multipart\").",
      "location": "query"
    }
  },
  "protocol": "rest",
  "mtlsRootUrl": "https://gmailpostmastertools.mtls.googleapis.com/",
  "baseUrl": "https://gmailpostmastertools.googleapis.com/",
  "auth": {
    "oauth2": {
      "scopes": {
        "https://www.googleapis.com/auth/postmaster.readonly": {
          "description": "See email traffic metrics for the domains you have registered in Gmail Postmaster Tools"
        }
      }
    }
  },
  "ownerName": "Google",
  "icons": {
    "x32": "http://www.google.com/images/icons/product/search-32.gif",
    "x16": "http://www.google.com/images/icons/product/search-16.gif"
  },
  "discoveryVersion": "v1",
  "title": "Gmail Postmaster Tools API",
  "documentationLink": "https://developers.google.com/gmail/postmaster",
  "kind": "discovery#restDescription",
  "resources": {
    "domains": {
      "methods": {
        "list": {
          "scopes": [
            "https://www.googleapis.com/auth/postmaster.readonly"
          ],
          "flatPath": "v1beta1/domains",
          "httpMethod": "GET",
          "response": {
            "$ref": "ListDomainsResponse"
          },
          "parameterOrder": [],
          "id": "gmailpostmastertools.domains.list",
          "description": "Lists the domains that have been registered by the client. The order of domains in the response is unspecified and non-deterministic. Newly created domains will not necessarily be added to the end of this list.",
          "parameters": {
            "pageSize": {
              "location": "query",
              "format": "int32",
              "description": "Requested page size. Server may return fewer domains than requested. If unspecified, server will pick an appropriate default.",
              "type": "integer"
            },
            "pageToken": {
              "type": "string",
              "description": "The next_page_token value returned from a previous List request, if any. This is the value of ListDomainsResponse.next_page_token returned from the previous call to `ListDomains` method.",
              "location": "query"
            }
          },
          "path": "v1beta1/domains"
        },
        "get": {
          "description": "Gets a specific domain registered by the client. Returns NOT_FOUND if the domain does not exist.",
          "scopes": [
            "https://www.googleapis.com/auth/postmaster.readonly"
          ],
          "id": "gmailpostmastertools.domains.get",
          "path": "v1beta1/{+name}",
          "response": {
            "$ref": "Domain"
          },
          "parameters": {
            "name": {
              "description": "The resource name of the domain. It should have the form `domains/{domain_name}`, where domain_name is the fully qualified domain name.",
              "type": "string",
              "pattern": "^domains/[^/]+$",
              "location": "path",
              "required": true
            }
          },
          "parameterOrder": [
            "name"
          ],
          "httpMethod": "GET",
          "flatPath": "v1beta1/domains/{domainsId}"
        }
      },
      "resources": {
        "trafficStats": {
          "methods": {
            "list": {
              "id": "gmailpostmastertools.domains.trafficStats.list",
              "parameterOrder": [
                "parent"
              ],
              "httpMethod": "GET",
              "path": "v1beta1/{+parent}/trafficStats",
              "parameters": {
                "startDate.month": {
                  "location": "query",
                  "description": "Month of a year. Must be from 1 to 12, or 0 to specify a year without a month and day.",
                  "format": "int32",
                  "type": "integer"
                },
                "startDate.year": {
                  "description": "Year of the date. Must be from 1 to 9999, or 0 to specify a date without a year.",
                  "format": "int32",
                  "location": "query",
                  "type": "integer"
                },
                "endDate.day": {
                  "format": "int32",
                  "description": "Day of a month. Must be from 1 to 31 and valid for the year and month, or 0 to specify a year by itself or a year and month where the day isn't significant.",
                  "location": "query",
                  "type": "integer"
                },
                "pageToken": {
                  "location": "query",
                  "description": "The next_page_token value returned from a previous List request, if any. This is the value of ListTrafficStatsResponse.next_page_token returned from the previous call to `ListTrafficStats` method.",
                  "type": "string"
                },
                "endDate.year": {
                  "format": "int32",
                  "type": "integer",
                  "description": "Year of the date. Must be from 1 to 9999, or 0 to specify a date without a year.",
                  "location": "query"
                },
                "endDate.month": {
                  "format": "int32",
                  "location": "query",
                  "description": "Month of a year. Must be from 1 to 12, or 0 to specify a year without a month and day.",
                  "type": "integer"
                },
                "parent": {
                  "pattern": "^domains/[^/]+$",
                  "location": "path",
                  "type": "string",
                  "description": "The resource name of the domain whose traffic statistics we'd like to list. It should have the form `domains/{domain_name}`, where domain_name is the fully qualified domain name.",
                  "required": true
                },
                "startDate.day": {
                  "format": "int32",
                  "location": "query",
                  "type": "integer",
                  "description": "Day of a month. Must be from 1 to 31 and valid for the year and month, or 0 to specify a year by itself or a year and month where the day isn't significant."
                },
                "pageSize": {
                  "location": "query",
                  "format": "int32",
                  "description": "Requested page size. Server may return fewer TrafficStats than requested. If unspecified, server will pick an appropriate default.",
                  "type": "integer"
                }
              },
              "flatPath": "v1beta1/domains/{domainsId}/trafficStats",
              "scopes": [
                "https://www.googleapis.com/auth/postmaster.readonly"
              ],
              "response": {
                "$ref": "ListTrafficStatsResponse"
              },
              "description": "List traffic statistics for all available days. Returns PERMISSION_DENIED if user does not have permission to access TrafficStats for the domain."
            },
            "get": {
              "flatPath": "v1beta1/domains/{domainsId}/trafficStats/{trafficStatsId}",
              "parameterOrder": [
                "name"
              ],
              "httpMethod": "GET",
              "scopes": [
                "https://www.googleapis.com/auth/postmaster.readonly"
              ],
              "parameters": {
                "name": {
                  "location": "path",
                  "description": "The resource name of the traffic statistics to get. E.g., domains/mymail.mydomain.com/trafficStats/20160807.",
                  "pattern": "^domains/[^/]+/trafficStats/[^/]+$",
                  "type": "string",
                  "required": true
                }
              },
              "response": {
                "$ref": "TrafficStats"
              },
              "id": "gmailpostmastertools.domains.trafficStats.get",
              "description": "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.",
              "path": "v1beta1/{+name}"
            }
          }
        }
      }
    }
  },
  "batchPath": "batch",
  "version_module": true,
  "description": "The Postmaster Tools API is a RESTful API that provides programmatic access to email traffic metrics (like spam reports, delivery errors etc) otherwise available through the Gmail Postmaster Tools UI currently.",
  "rootUrl": "https://gmailpostmastertools.googleapis.com/",
  "servicePath": ""
}