DomainCanary C API

openapi: 3.2.0
info:
  title: DomainCanary free C API
  version: 1.0.0
  summary: Check a domain's email authentication and test SPF changes, with no key.
  description: 'The free JSON API checks a domain''s DMARC, SPF and DKIM records and lists what to fix. It also compares a new SPF record with the one you publish today and lists the senders that would fail SPF under the new one. You don''t need an account or a key.


    DomainCanary is a DMARC enforcement service that protects your domain from email spoofing without blocking your own mail. The calls run the same checks as the free tools on the site.


    Calls share an allowance of 30 lookups per IP address with the free tools on the site. A domain check counts as 5 lookups, or 6 when it checks a blocklist. An SPF pre-flight counts as 2. Once you''ve used the allowance, the API answers 429 with a Retry-After header, and the count starts again 10 minutes after your last call.


    AI assistants can run the same checks over MCP at https://domaincanary.com/mcp.'
  termsOfService: https://domaincanary.com/terms
  contact:
    name: DomainCanary
    email: contact@domaincanary.com
    url: https://domaincanary.com/about
servers:
- url: https://domaincanary.com
tags:
- name: C
paths:
  /c/{domain}:
    get:
      operationId: checkDomain
      summary: Check a domain's email authentication
      description: Looks up the domain's DMARC, SPF and DKIM records, where its DMARC reports go, its MX records, the SpamCop blocklist, MTA-STS, TLS-RPT and BIMI. The answer lists every problem worst first, with the record to publish where one fixes it. It is the email health check from the site, as JSON.
      externalDocs:
        description: Email health check
        url: https://domaincanary.com/tools/checkup
      parameters:
      - name: domain
        in: path
        required: true
        description: The domain to check, as in example.com.
        schema:
          type: string
          maxLength: 253
        example: example.com
      - name: format
        in: query
        required: true
        description: json for this answer. txt returns the same report as plain text. Leave it out and you get the HTML page.
        schema:
          type: string
          enum:
          - json
          - txt
        example: json
      responses:
        '200':
          description: The report.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckReport'
            text/plain:
              schema:
                type: string
        '400':
          description: The domain is not a valid domain name, so we did not look anything up.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            text/plain:
              schema:
                type: string
        '429':
          description: Your IP address has used its allowance.
          headers:
            Retry-After:
              description: Seconds to wait before you call again.
              schema:
                type: integer
                minimum: 1
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottleError'
            text/plain:
              schema:
                type: string
      tags:
      - C
components:
  schemas:
    CheckRow:
      type: object
      properties:
        status:
          type: string
          enum:
          - ok
          - warn
          - error
          - unknown
        summary:
          type: string
          description: One clause on how the check came out.
        detail:
          type: string
          description: The record or value the check read, when there is one.
      required:
      - status
      - summary
      additionalProperties: false
    ThrottleError:
      type: object
      properties:
        error:
          type: string
        retry_after:
          type: integer
          minimum: 1
          description: Seconds until you can call again.
      required:
      - error
      - retry_after
      additionalProperties: false
    Error:
      type: object
      properties:
        error:
          type: string
          description: What went wrong, in one sentence.
      required:
      - error
      additionalProperties: false
    CheckReport:
      type: object
      properties:
        domain:
          type: string
          description: The domain checked, in lowercase.
        url:
          type: string
          description: The address of the same report as a web page.
        complete:
          type: boolean
          description: False when a lookup did not complete. An empty issues list then proves nothing.
        issues:
          type: array
          description: Every error and warning, worst first.
          items:
            type: object
            properties:
              check:
                type: string
                enum:
                - dmarc
                - spf
                - dkim
                - reports
                - mx
                - blocklists
                - mta-sts
                - tls-rpt
                - bimi
              level:
                type: string
                enum:
                - error
                - warn
              message:
                type: string
              fix:
                type: object
                description: A record that fixes the issue, ready to publish.
                properties:
                  name:
                    type: string
                    description: The DNS name to publish at.
                  type:
                    type: string
                    const: TXT
                  value:
                    type: string
                    description: The exact record value.
                  note:
                    type: string
                    description: What to do before you publish it.
                required:
                - name
                - type
                - value
                additionalProperties: false
            required:
            - check
            - level
            - message
            additionalProperties: false
        checks:
          type: object
          description: One entry per check. A domain whose null MX says it takes no mail has no mta-sts or tls-rpt entry.
          properties:
            dmarc:
              $ref: '#/components/schemas/CheckRow'
            spf:
              $ref: '#/components/schemas/CheckRow'
            dkim:
              $ref: '#/components/schemas/CheckRow'
            reports:
              $ref: '#/components/schemas/CheckRow'
            mx:
              $ref: '#/components/schemas/CheckRow'
            blocklists:
              $ref: '#/components/schemas/CheckRow'
            mta-sts:
              $ref: '#/components/schemas/CheckRow'
            tls-rpt:
              $ref: '#/components/schemas/CheckRow'
            bimi:
              $ref: '#/components/schemas/CheckRow'
          required:
          - dmarc
          - spf
          - dkim
          - reports
          - mx
          - blocklists
          - bimi
          additionalProperties: false
        blocklists_checked:
          type: array
          items:
            type: string
      required:
      - domain
      - url
      - complete
      - issues
      - checks
      - blocklists_checked
      additionalProperties: false