openapi: 3.0.0
servers:
  - url: https://gmailpostmastertools.googleapis.com/
info:
  contact:
    name: Google
    url: https://google.com
    x-twitter: youtube
  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.
  license:
    name: Creative Commons Attribution 3.0
    url: http://creativecommons.org/licenses/by/3.0/
  termsOfService: https://developers.google.com/terms/
  title: Gmail Postmaster Tools API
  version: v1
  x-apisguru-categories:
    - analytics
    - media
  x-logo:
    url: https://api.apis.guru/v2/cache/logo/https_upload.wikimedia.org_wikipedia_commons_e_e1_YouTube_play_buttom_icon_%282013-2017%29.svg
  x-origin:
    - format: openapi
      url: https://gmailpostmastertools.googleapis.com/$discovery/rest?version=v1
      version: "3.0"
  x-preferred: false
  x-providerName: googleapis.com
  x-serviceName: gmailpostmastertools
externalDocs:
  url: https://developers.google.com/gmail/postmaster
tags:
  - name: domains
paths:
  /v1/domains:
    get:
      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.
      operationId: gmailpostmastertools.domains.list
      parameters:
        - description: Requested page size. Server may return fewer domains than requested. If unspecified, server will pick an appropriate default.
          in: query
          name: pageSize
          schema:
            type: integer
        - 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.
          in: query
          name: pageToken
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListDomainsResponse"
          description: Successful response
      security:
        - Oauth2:
            - https://www.googleapis.com/auth/postmaster.readonly
          Oauth2c:
            - https://www.googleapis.com/auth/postmaster.readonly
      tags:
        - domains
    parameters:
      - $ref: "#/components/parameters/_.xgafv"
      - $ref: "#/components/parameters/access_token"
      - $ref: "#/components/parameters/alt"
      - $ref: "#/components/parameters/callback"
      - $ref: "#/components/parameters/fields"
      - $ref: "#/components/parameters/key"
      - $ref: "#/components/parameters/oauth_token"
      - $ref: "#/components/parameters/prettyPrint"
      - $ref: "#/components/parameters/quotaUser"
      - $ref: "#/components/parameters/upload_protocol"
      - $ref: "#/components/parameters/uploadType"
  "/v1/{name}":
    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.
      operationId: gmailpostmastertools.domains.trafficStats.get
      parameters:
        - description: The resource name of the traffic statistics to get. E.g., domains/mymail.mydomain.com/trafficStats/20160807.
          in: path
          name: name
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TrafficStats"
          description: Successful response
      security:
        - Oauth2:
            - https://www.googleapis.com/auth/postmaster.readonly
          Oauth2c:
            - https://www.googleapis.com/auth/postmaster.readonly
      tags:
        - domains
    parameters:
      - $ref: "#/components/parameters/_.xgafv"
      - $ref: "#/components/parameters/access_token"
      - $ref: "#/components/parameters/alt"
      - $ref: "#/components/parameters/callback"
      - $ref: "#/components/parameters/fields"
      - $ref: "#/components/parameters/key"
      - $ref: "#/components/parameters/oauth_token"
      - $ref: "#/components/parameters/prettyPrint"
      - $ref: "#/components/parameters/quotaUser"
      - $ref: "#/components/parameters/upload_protocol"
      - $ref: "#/components/parameters/uploadType"
  "/v1/{parent}/trafficStats":
    get:
      description: List traffic statistics for all available days. Returns PERMISSION_DENIED if user does not have permission to access TrafficStats for the domain.
      operationId: gmailpostmastertools.domains.trafficStats.list
      parameters:
        - 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.
          in: path
          name: parent
          required: true
          schema:
            type: string
        - 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.
          in: query
          name: endDate.day
          schema:
            type: integer
        - description: Month of a year. Must be from 1 to 12, or 0 to specify a year without a month and day.
          in: query
          name: endDate.month
          schema:
            type: integer
        - description: Year of the date. Must be from 1 to 9999, or 0 to specify a date without a year.
          in: query
          name: endDate.year
          schema:
            type: integer
        - description: Requested page size. Server may return fewer TrafficStats than requested. If unspecified, server will pick an appropriate default.
          in: query
          name: pageSize
          schema:
            type: integer
        - 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.
          in: query
          name: pageToken
          schema:
            type: string
        - 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.
          in: query
          name: startDate.day
          schema:
            type: integer
        - description: Month of a year. Must be from 1 to 12, or 0 to specify a year without a month and day.
          in: query
          name: startDate.month
          schema:
            type: integer
        - description: Year of the date. Must be from 1 to 9999, or 0 to specify a date without a year.
          in: query
          name: startDate.year
          schema:
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListTrafficStatsResponse"
          description: Successful response
      security:
        - Oauth2:
            - https://www.googleapis.com/auth/postmaster.readonly
          Oauth2c:
            - https://www.googleapis.com/auth/postmaster.readonly
      tags:
        - domains
    parameters:
      - $ref: "#/components/parameters/_.xgafv"
      - $ref: "#/components/parameters/access_token"
      - $ref: "#/components/parameters/alt"
      - $ref: "#/components/parameters/callback"
      - $ref: "#/components/parameters/fields"
      - $ref: "#/components/parameters/key"
      - $ref: "#/components/parameters/oauth_token"
      - $ref: "#/components/parameters/prettyPrint"
      - $ref: "#/components/parameters/quotaUser"
      - $ref: "#/components/parameters/upload_protocol"
      - $ref: "#/components/parameters/uploadType"
components:
  parameters:
    _.xgafv:
      description: V1 error format.
      in: query
      name: $.xgafv
      schema:
        enum:
          - "1"
          - "2"
        type: string
    access_token:
      description: OAuth access token.
      in: query
      name: access_token
      schema:
        type: string
    alt:
      description: Data format for response.
      in: query
      name: alt
      schema:
        enum:
          - json
          - media
          - proto
        type: string
    callback:
      description: JSONP
      in: query
      name: callback
      schema:
        type: string
    fields:
      description: Selector specifying which fields to include in a partial response.
      in: query
      name: fields
      schema:
        type: string
    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.
      in: query
      name: key
      schema:
        type: string
    oauth_token:
      description: OAuth 2.0 token for the current user.
      in: query
      name: oauth_token
      schema:
        type: string
    prettyPrint:
      description: Returns response with indentations and line breaks.
      in: query
      name: prettyPrint
      schema:
        type: boolean
    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.
      in: query
      name: quotaUser
      schema:
        type: string
    uploadType:
      description: Legacy upload protocol for media (e.g. "media", "multipart").
      in: query
      name: uploadType
      schema:
        type: string
    upload_protocol:
      description: Upload protocol for media (e.g. "raw", "multipart").
      in: query
      name: upload_protocol
      schema:
        type: string
  schemas:
    DeliveryError:
      description: Metric on a particular delivery error type.
      properties:
        errorClass:
          description: The class of delivery error.
          enum:
            - DELIVERY_ERROR_CLASS_UNSPECIFIED
            - PERMANENT_ERROR
            - TEMPORARY_ERROR
          type: string
        errorRatio:
          description: The ratio of messages where the error occurred vs all authenticated traffic.
          format: double
          type: number
        errorType:
          description: The type of delivery error.
          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: string
      type: object
    Domain:
      description: A registered domain resource in the Postmaster API.
      properties:
        createTime:
          description: Timestamp when the user registered this domain. Assigned by the server.
          format: google-datetime
          type: string
        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.
          enum:
            - PERMISSION_UNSPECIFIED
            - OWNER
            - READER
            - NONE
          type: string
      type: object
    FeedbackLoop:
      description: "[Feedback loop](https://support.google.com/mail/answer/6254652) identifier information."
      properties:
        id:
          description: Feedback loop identifier that uniquely identifies individual campaigns.
          type: string
        spamRatio:
          description: The ratio of user marked spam messages with the identifier vs the total number of inboxed messages with that identifier.
          format: double
          type: number
      type: object
    IpReputation:
      description: IP Reputation information for a set of IPs in a specific reputation category.
      properties:
        ipCount:
          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/).
          format: int64
          type: string
        reputation:
          description: The reputation category this IP reputation represents.
          enum:
            - REPUTATION_CATEGORY_UNSPECIFIED
            - HIGH
            - MEDIUM
            - LOW
            - BAD
          type: string
        sampleIps:
          description: A sample of IPs in this reputation category.
          items:
            type: string
          type: array
      type: object
    ListDomainsResponse:
      description: Response message for ListDomains.
      properties:
        domains:
          description: The list of domains.
          items:
            $ref: "#/components/schemas/Domain"
          type: array
        nextPageToken:
          description: Token to retrieve the next page of results, or empty if there are no more results in the list.
          type: string
      type: object
    ListTrafficStatsResponse:
      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:
          description: The list of TrafficStats.
          items:
            $ref: "#/components/schemas/TrafficStats"
          type: array
      type: object
    TrafficStats:
      description: Email traffic statistics pertaining to a specific date.
      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/).
          items:
            $ref: "#/components/schemas/DeliveryError"
          type: array
        dkimSuccessRatio:
          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.
          format: double
          type: number
        dmarcSuccessRatio:
          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/).
          format: double
          type: number
        domainReputation:
          description: Reputation of the domain.
          enum:
            - REPUTATION_CATEGORY_UNSPECIFIED
            - HIGH
            - MEDIUM
            - LOW
            - BAD
          type: string
        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
        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: "#/components/schemas/IpReputation"
          type: array
        name:
          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"
          type: string
        outboundEncryptionRatio:
          description: The ratio of outgoing mail (from Gmail) that was accepted over secure transport (TLS).
          format: double
          type: number
        spammyFeedbackLoops:
          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: "#/components/schemas/FeedbackLoop"
          type: array
        spfSuccessRatio:
          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.
          format: double
          type: number
        userReportedSpamRatio:
          description: The ratio of user-report spam vs. email that was sent to the inbox. This metric only pertains to emails authenticated by [DKIM](http://www.dkim.org/).
          format: double
          type: number
      type: object
  securitySchemes:
    Oauth2:
      description: Oauth 2.0 implicit authentication
      flows:
        implicit:
          authorizationUrl: https://accounts.google.com/o/oauth2/auth
          scopes:
            https://www.googleapis.com/auth/postmaster.readonly: See email traffic metrics for the domains you have registered in Gmail Postmaster Tools
      type: oauth2
    Oauth2c:
      description: Oauth 2.0 authorizationCode authentication
      flows:
        authorizationCode:
          authorizationUrl: https://accounts.google.com/o/oauth2/auth
          scopes:
            https://www.googleapis.com/auth/postmaster.readonly: See email traffic metrics for the domains you have registered in Gmail Postmaster Tools
          tokenUrl: https://accounts.google.com/o/oauth2/token
      type: oauth2
