### Install pip on Debian/Ubuntu

Source: https://github.com/domainaware/checkdmarc/blob/main/docs/source/installation.md

Use this command to install the pip package manager on Debian or Ubuntu systems, which is a prerequisite for installing checkdmarc.

```text
sudo apt-get install python3-pip
```

--------------------------------

### Install checkdmarc Development Release from GitHub

Source: https://github.com/domainaware/checkdmarc/blob/main/docs/source/installation.md

Install the latest development release of checkdmarc directly from its GitHub repository using pip3.

```text
pip3 install -U git+https://github.com/domainaware/checkdmarc.git
```

--------------------------------

### CLI Example with Public DNS Resolvers

Source: https://github.com/domainaware/checkdmarc/blob/main/docs/source/cli.md

Demonstrates how to specify public DNS resolvers for more reliable internet checks. This command queries proton.me using Cloudflare and Google's DNS servers, skipping TLS testing.

```bash
checkdmarc -n 1.1.1.1 8.8.8.8 --skip-tls proton.me
```

--------------------------------

### API Example with Recommended DNS Resolvers

Source: https://github.com/domainaware/checkdmarc/blob/main/docs/source/cli.md

Shows how to use the recommended public DNS resolvers in the checkdmarc Python API for checking domains. This ensures cross-provider failover for DNS queries.

```python
from checkdmarc import check_domains, RECOMMENDED_DNS_NAMESERVERS

results = check_domains(
    ["proton.me"],
    nameservers=RECOMMENDED_DNS_NAMESERVERS,
)
```

--------------------------------

### checkdmarc.utils.get_nameservers

Source: https://github.com/domainaware/checkdmarc/blob/main/docs/source/api.md

Gets a list of nameservers for a given domain.

```APIDOC
## checkdmarc.utils.get_nameservers

### Description
Gets a list of nameservers for a given domain.

### Parameters
* **domain** (*str*) – A domain name
* **approved_nameservers** (*list*) – A list of approved nameserver substrings
* **nameservers** (*list*) – A list of nameservers to query
* **resolver** (*dns.resolver.Resolver*) – A resolver object to use for DNS requests
* **timeout** (*float*) – number of seconds to wait for a record from DNS
* **retries** (*int*) – The number of times to retry on timeout or other transient errors

### Returns
A dictionary with the following keys:
  - `hostnames` - A list of nameserver hostnames
  - `warnings`  - A list of warnings

### Return type
dict
```

--------------------------------

### Install checkdmarc Stable Release

Source: https://github.com/domainaware/checkdmarc/blob/main/docs/source/installation.md

Install or upgrade to the latest stable release of checkdmarc using pip3 on macOS or Linux.

```text
pip3 install -U checkdmarc
```

--------------------------------

### checkdmarc JSON Output Example

Source: https://github.com/domainaware/checkdmarc/blob/main/docs/source/cli.md

Example of the detailed JSON output provided by checkdmarc for a domain, including DNSSEC, SOA, NS, MX, MTA-STS, SPF, and DMARC records.

```json
{
  "domain": "proton.me",
  "base_domain": "proton.me",
  "dnssec": true,
  "soa": {
    "record": "ns1.proton.me. support.proton.me. 2025091157 1200 144 1814400 7200",
    "values": {
      "primary_nameserver": "ns1.proton.me",
      "rname_email_address": "support@proton.me",
      "serial": 2025091157,
      "refresh": 1200,
      "retry": 144,
      "expire": 1814400,
      "minimum": 7200
    }
  },
  "ns": {
    "hostnames": [
      "ns1.proton.me",
      "ns2.proton.me",
      "ns3.proton.me"
    ],
    "warnings": []
  },
  "mx": {
    "hosts": [
      {
        "preference": 10,
        "hostname": "mail.protonmail.ch",
        "addresses": [
          "176.119.200.128",
          "185.205.70.128",
          "185.70.42.128"
        ],
        "dnssec": true,
        "tlsa": [
          "3 1 1 6111a5698d23c89e09c36ff833c1487edc1b0c841f87c49dae8f7a09e11e979e",
          "3 1 1 76bb66711da416433ca890a5b2e5a0533c6006478f7d10a4469a947acc8399e1"
        ]
      },
      {
        "preference": 20,
        "hostname": "mailsec.protonmail.ch",
        "addresses": [
          "176.119.200.129",
          "185.205.70.129",
          "185.70.42.129"
        ],
        "dnssec": true,
        "tlsa": [
          "3 1 1 6111a5698d23c89e09c36ff833c1487edc1b0c841f87c49dae8f7a09e11e979e",
          "3 1 1 76bb66711da416433ca890a5b2e5a0533c6006478f7d10a4469a947acc8399e1"
        ]
      }
    ],
    "warnings": []
  },
  "mta_sts": {
    "valid": true,
    "id": "190906205100Z",
    "policy": {
      "version": "STSv1",
      "mode": "enforce",
      "max_age": 604800,
      "mx": [
        "mail.protonmail.ch",
        "mailsec.protonmail.ch"
      ]
    },
    "warnings": []
  },
  "spf": {
    "record": "v=spf1 include:_spf.protonmail.ch ~all",
    "valid": true,
    "dns_lookups": 2,
    "void_dns_lookups": 0,
    "warnings": [],
    "parsed": {
      "mechanisms": [
        {
          "mechanism": "include",
          "value": "_spf.protonmail.ch",
          "record": "v=spf1 ip4:185.70.40.0/24 ip4:185.70.41.0/24 ip4:185.70.43.0/24 ip4:79.135.106.0/24 ip4:79.135.107.0/24 ip4:109.224.244.0/24 include:_spf2.protonmail.ch ~all",
          "dns_lookups": 2,
          "void_dns_lookups": 0,
          "parsed": {
            "mechanisms": [
              {
                "mechanism": "ip4",
                "value": "185.70.40.0/24",
                "action": "pass"
              },
              {
                "mechanism": "ip4",
                "value": "185.70.41.0/24",
                "action": "pass"
              },
              {
                "mechanism": "ip4",
                "value": "185.70.43.0/24",
                "action": "pass"
              },
              {
                "mechanism": "ip4",
                "value": "79.135.106.0/24",
                "action": "pass"
              },
              {
                "mechanism": "ip4",
                "value": "79.135.107.0/24",
                "action": "pass"
              },
              {
                "mechanism": "ip4",
                "value": "109.224.244.0/24",
                "action": "pass"
              },
              {
                "mechanism": "include",
                "value": "_spf2.protonmail.ch",
                "record": "v=spf1 ip4:85.9.206.169 ip4:85.9.210.45 ip4:188.165.51.139 ip4:57.129.93.249 ~all",
                "dns_lookups": 1,
                "void_dns_lookups": 0,
                "parsed": {
                  "mechanisms": [
                    {
                      "mechanism": "ip4",
                      "value": "85.9.206.169",
                      "action": "pass"
                    },
                    {
                      "mechanism": "ip4",
                      "value": "85.9.210.45",
                      "action": "pass"
                    },
                    {
                      "mechanism": "ip4",
                      "value": "188.165.51.139",
                      "action": "pass"
                    },
                    {
                      "mechanism": "ip4",
                      "value": "57.129.93.249",
                      "action": "pass"
                    }
                  ],
                  "redirect": null,
                  "exp": null,
                  "all": "softfail"
                },
                "warnings": []
              }
            ],
            "redirect": null,
            "exp": null,
            "all": "softfail"
          },
          "warnings": []
        }
      ],
      "redirect": null,
      "exp": null,
      "all": "softfail"
    }
  },
  "dmarc": {
    "record": "v=DMARC1; p=quarantine; fo=1; aspf=s; adkim=s;",
    "valid": true,
    "location": "proton.me",
    "warnings": [
      "rua tag (destination for aggregate reports) not found."
    ],
    "tags": {
      "v": {
        "value": "DMARC1",
        "explicit": true
      },
      "p": {
        "value": "quarantine",
        "explicit": true
      },
      "fo": {
        "value": "1",
        "explicit": true
      },
      "aspf": {
        "value": "s",
        "explicit": true
      },
      "adkim": {
        "value": "s",
        "explicit": true
      }
    }
  }
}
```

--------------------------------

### DMARC Record Analysis Example

Source: https://github.com/domainaware/checkdmarc/blob/main/docs/source/cli.md

This JSON snippet represents the parsed output of a DMARC record analysis, detailing various policy settings and tags.

```json
{
  "value": "quarantine",
  "explicit": true
},
"fo": {
  "value": "1",
  "explicit": true
},
"aspf": {
  "value": "s",
  "explicit": true
},
"adkim": {
  "value": "s",
  "explicit": true
},
"pct": {
  "value": 100,
  "explicit": false
},
"rf": {
  "value": "afrf",
  "explicit": false
},
"ri": {
  "value": 86400,
  "explicit": false
},
"sp": {
  "value": "quarantine",
  "explicit": false
}
}
},
"smtp_tls_reporting": {
"valid": true,
"tags": {
"v": {
"value": "TLSRPTv1"
},
"rua": {
"value": [
"https://reports.proton.me/reports/smtptls"
]
}
},
"warnings": []
},
"bimi": {
"record": "v=BIMI1; l=; a=;";
"valid": true,
"selector": "default",
"location": "proton.me",
"tags": {
"v": {
"value": "BIMI1"
},
"l": {
"value": ""
},
"a": {
"value": ""
}
},
"warnings": []
}
}
```

--------------------------------

### get_dmarc_tag_description

Source: https://github.com/domainaware/checkdmarc/blob/main/docs/source/api.md

Get the name, default value, and description for a DMARC tag, and/or a description for a tag value.

```APIDOC
## get_dmarc_tag_description(tag: str, value: str | list[str] | None = None) -> dict

### Description
Get the name, default value, and description for a DMARC tag, and/or a description for a tag value.

### Parameters
#### Path Parameters
- **tag** (str) - Required - A DMARC tag
- **value** (str | list[str] | None) - Optional - An optional value

### Returns
- **dict** - a `dict` with the following keys:
  - `name` - the tag name
  - `default` - the tag’s default value
  - `description` - A description of the tag or value
```

--------------------------------

### checkdmarc.utils.get_base_domain

Source: https://github.com/domainaware/checkdmarc/blob/main/docs/source/api.md

Gets the base domain name for a given domain.

```APIDOC
## checkdmarc.utils.get_base_domain(domain: str) -> str

### Description
Gets the base domain name for the given domain

### Parameters
#### Path Parameters
* **domain** (str) - Required - A domain name

### Returns
The base domain name

### Return type
str
```

--------------------------------

### Build documentation

Source: https://github.com/domainaware/checkdmarc/blob/main/AGENTS.md

Compile the project documentation using Sphinx. Navigate to the docs directory before running.

```bash
cd docs && make html
```

--------------------------------

### Full build script

Source: https://github.com/domainaware/checkdmarc/blob/main/AGENTS.md

Execute a comprehensive build process including formatting, documentation, and package building.

```bash
./build.sh
```

--------------------------------

### Lint and format code with Ruff

Source: https://github.com/domainaware/checkdmarc/blob/main/AGENTS.md

Apply code linting and formatting using Ruff. Use `--show-fixes` to see changes that would be applied.

```bash
ruff check --show-fixes
```

```bash
ruff format .
```

--------------------------------

### Run tests with coverage

Source: https://github.com/domainaware/checkdmarc/blob/main/AGENTS.md

Execute tests and generate a coverage report. This command is useful for assessing test completeness.

```bash
coverage run tests.py
```

--------------------------------

### Build checkdmarc Docker Image

Source: https://github.com/domainaware/checkdmarc/blob/main/README.md

Build the Docker image for checkdmarc using the provided Dockerfile.

```bash
docker build . -t checkdmarc
```

--------------------------------

### Run checkdmarc Docker Container

Source: https://github.com/domainaware/checkdmarc/blob/main/README.md

Execute the checkdmarc Docker container to analyze a domain. Replace 'google.nl' with the domain you want to check.

```bash
docker run --rm checkdmarc google.nl
```

--------------------------------

### checkdmarc.smtp.test_starttls

Source: https://github.com/domainaware/checkdmarc/blob/main/docs/source/api.md

Attempts to connect to an SMTP server and validates STARTTLS support.

```APIDOC
## checkdmarc.smtp.test_starttls

### Description
Attempt to connect to an SMTP server and validate STARTTLS support.

### Method
Not applicable (Python function)

### Endpoint
Not applicable (Python function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **hostname** (*str*) – The hostname
* **ssl_context** (*SSLContext*) – A SSL context (Optional, default: None)
* **cache** (*ExpiringDict*) – Cache storage (Optional, default: None)
* **timeout** (*float*) – number of seconds to wait for a connection (Optional, default: 5.0)

### Response
#### Success Response
Returns `True` if STARTTLS is supported.

#### Response Example
```
True
```

#### Error Response
* **checkdmarc.smtp.SMTPError** – SMTP connection failed.
```

--------------------------------

### Build Python package with Hatch

Source: https://github.com/domainaware/checkdmarc/blob/main/AGENTS.md

Build the distributable package for the checkdmarc library using Hatchling.

```bash
hatch build
```

--------------------------------

### Handling SPF Parsing Results (Python)

Source: https://github.com/domainaware/checkdmarc/blob/main/CHANGELOG.md

Demonstrates how to iterate over SPF record results after the parsing structure change. Previously, direct access to keys like 'pass' was used; now, filter the 'mechanisms' list by the 'action' key.

```python
for item in parsed["pass"]:
    ...
```

```python
for m in parsed["mechanisms"]:
    if m["action"] == "pass":
        ...

```

--------------------------------

### checkdmarc CLI Usage

Source: https://github.com/domainaware/checkdmarc/blob/main/docs/source/cli.md

Displays the help message and all available options for the checkdmarc CLI tool. Use this to understand the full range of commands and arguments.

```text
usage: checkdmarc [-h] [-p] [--ns NS [NS ...]] [--mx MX [MX ...]] [-d] [-f FORMAT]
                  [-o OUTPUT [OUTPUT ...]] [-n NAMESERVER [NAMESERVER ...]] [-t TIMEOUT]
                  [-b BIMI_SELECTOR] [-v] [-w WAIT] [--skip-tls] [--debug]
                  domain [domain ...]

Validates and parses email-related DNS records

positional arguments:
  domain                one or more domains, or a single path to a file containing a
                        list of domains

options:
  -h, --help            show this help message and exit
  -p, --parked          indicate that the domains are parked
  --ns NS [NS ...]      approved nameserver substrings
  --mx MX [MX ...]      approved MX hostname substrings
  -d, --descriptions    include descriptions of tags in the JSON output
  -f FORMAT, --format FORMAT
                        specify JSON or CSV screen output format
  -o OUTPUT [OUTPUT ...], --output OUTPUT [OUTPUT ...]
                        one or more file paths to output to (must end in .json or .csv)
                        (silences screen output)
  -n NAMESERVER [NAMESERVER ...], --nameserver NAMESERVER [NAMESERVER ...]
                        nameservers to query (default: the system-configured
                        resolvers). For reliability, passing a mix of public
                        resolvers is recommended, e.g. 1.1.1.1 8.8.8.8
  -t TIMEOUT, --timeout TIMEOUT
                        number of seconds to wait for an answer from DNS (default 2.0)
  -b BIMI_SELECTOR, --bimi-selector BIMI_SELECTOR
                        The BIMI selector to use (default default)
  -v, --version         show program's version number and exit
  -w WAIT, --wait WAIT  number of seconds to wait between checking domains (default 0.0)
  --skip-tls            skip TLS/SSL testing
  --debug               enable debugging output
```

--------------------------------

### check_ns

Source: https://github.com/domainaware/checkdmarc/blob/main/docs/source/api.md

Retrieves nameserver information and associated warnings for a given domain, or an error message if a DNS error occurs.

```APIDOC
## check_ns

### Description
Returns a dictionary of nameservers and warnings or a dictionary with an empty list and an error.

### Method
checkdmarc.check_ns

### Parameters
#### Path Parameters
- **domain** (str) - Required - A domain name
- **approved_nameservers** (list) - Optional - A list of approved nameserver substrings
- **nameservers** (list) - Optional - A list of nameservers to query
- **resolver** (dns.resolver.Resolver) - Optional - A resolver object to use for DNS requests
- **timeout** (float) - Optional - number of seconds to wait for a record from DNS

### Returns
A dictionary with the following keys:
- `hostnames` - A list of nameserver hostnames
- `warnings`  - A list of warnings

If a DNS error occurs, the dictionary will have the following keys:
- `hostnames` - An empty list
- `error`  - An error message

### Return type
dict
```

--------------------------------

### download_mta_sts_policy

Source: https://github.com/domainaware/checkdmarc/blob/main/docs/source/api.md

Downloads a domain's MTA-STS policy from its web server.

```APIDOC
## download_mta_sts_policy

### Description
Downloads a domain's MTA-STS policy.

### Method
download_mta_sts_policy

### Parameters
#### Path Parameters
- **domain** (str) - Required - A domain name
- **http_timeout** (float) - Optional - HTTP timeout in seconds (default: 2.0)

### Returns
- **Success**: a `dict` with the following keys:
  - `policy` (str) - The unparsed policy string
  - `warnings` (list) - A list of any warning conditions found

### Raises
- **checkdmarc.mta_sts.MTASTSPolicyDownloadError** - If the policy download fails.
```

--------------------------------

### SPF Record Parsing Structure Change (JSON)

Source: https://github.com/domainaware/checkdmarc/blob/main/CHANGELOG.md

Illustrates the change in SPF record parsing output structure from top-level keys to a 'mechanisms' list. Use this when consuming SPF evaluation results in JSON format.

```json
"pass": [...]
```

```json
"mechanisms": [
  {
    "mechanism": "mx",
    "value": "example.com",
    "dns_lookups": 3,
    "void_dns_lookups": 0,
    "action": "pass",
    "hosts": {
      "mx1.example.com": ["203.0.113.10"]
    }
  },
  {
    "mechanism": "a",
    "value": "example.com",
    "dns_lookups": 1,
    "void_dns_lookups": 0,
    "action", "pass",
    "addresses": [
     "23.192.228.80",
     "2600:1406:5e00:6::17ce:bc12"
   ]
  }
]
```

--------------------------------

### Run a specific test with Pytest

Source: https://github.com/domainaware/checkdmarc/blob/main/AGENTS.md

Execute a single test case using Pytest by specifying a test name with the -k flag. Useful for targeted debugging.

```bash
python -m pytest tests.py -k "test_name"
```

--------------------------------

### Run checkdmarc on a domain

Source: https://github.com/domainaware/checkdmarc/blob/main/docs/source/cli.md

Execute a DMARC check on a specified domain, skipping TLS verification. The output is displayed in JSON format.

```bash
checkdmarc --skip-tls proton.me
```

--------------------------------

### check_spf

Source: https://github.com/domainaware/checkdmarc/blob/main/docs/source/api.md

Returns a dictionary with a parsed SPF record or an error. This function queries DNS for the SPF record of a given domain and parses it.

```APIDOC
## check_spf(domain: str, parked: bool = False, nameservers: Sequence[str | Nameserver] | None = None, resolver: Resolver | None = None, timeout: float = 2.0, retries: int = 0) -> dict

### Description
Returns a dictionary with a parsed SPF record or an error.

### Parameters
#### Path Parameters
- **domain** (str) - Required - A domain name
- **parked** (bool) - Optional - The domain is parked
- **nameservers** (Sequence[str | Nameserver] | None) - Optional - A list of nameservers to query
- **resolver** (dns.resolver.Resolver | None) - Optional - A resolver object to use for DNS requests
- **timeout** (float) - Optional - number of seconds to wait for an answer from DNS
- **retries** (int) - Optional - The number of times to retry on timeout or other transient errors

### Returns
#### Success Response (dict)
- **record** (str) - The SPF record string
- **parsed** (dict) - The parsed SPF record
- **dns_lookups** (int) - The number of DNS lookups
- **void_dns_lookups** (int) - The number of void DNS lookups
- **valid** (bool) - True
- **warnings** (list) - A list of warnings

#### Error Response (dict)
- **error** (str) - The error message
- **valid** (bool) - False
```

--------------------------------

### checkdmarc.utils.get_txt_records

Source: https://github.com/domainaware/checkdmarc/blob/main/docs/source/api.md

Queries DNS for TXT records.

```APIDOC
## checkdmarc.utils.get_txt_records

### Description
Queries DNS for TXT records.

### Parameters
* **domain** (*str*) – A domain name
* **quoted_txt_segments** (*bool*) – Preserve quotes in TXT records
* **nameservers** (*list*) – A list of nameservers to query
* **resolver** (*dns.resolver.Resolver*) – A resolver object to use for DNS requests
* **timeout** (*float*) – number of seconds to wait for an answer from DNS
* **retries** (*int*) – The number of times to retry on timeout or other transient errors

### Returns
A list of TXT records

### Return type
list

### Raises
**checkdmarc.DNSException** –
```

--------------------------------

### check_mx

Source: https://github.com/domainaware/checkdmarc/blob/main/docs/source/api.md

Retrieves Mail Exchanger (MX) hostnames and their IP addresses for a given domain, with optional TLS checks.

```APIDOC
## check_mx

### Description
Retrieves the Mail Exchanger (MX) hostnames and their corresponding IP addresses for a specified domain. It can optionally skip TLS testing and consider approved MX hostnames or MTA-STS patterns. Returns success or failure results, including any warnings or errors encountered during DNS resolution.

### Method
`checkdmarc.smtp.check_mx`

### Parameters
#### Path Parameters
- **domain** (str) - Required - The domain name for which to check MX records.
- **skip_tls** (bool) - Optional - If True, STARTTLS testing will be skipped. Defaults to False.
- **approved_mx_hostnames** (list[str]) - Optional - A list of MX hostname substrings that are considered approved.
- **mta_sts_mx_patterns** (list[str]) - Optional - A list of MX patterns extracted from MTA-STS policies.
- **nameservers** (Sequence[str | Nameserver]) - Optional - A list of nameservers to query. Defaults to None.
- **resolver** (Resolver) - Optional - A `dns.resolver.Resolver` object to use for DNS requests. Defaults to None.
- **timeout** (float) - Optional - The number of seconds to wait for a response from the DNS server. Defaults to 2.0.
- **retries** (int) - Optional - The number of times to retry the query in case of timeouts or transient errors. Defaults to 0.

### Returns
A dictionary containing:
- `hosts`: A list of dictionaries, where each dictionary has 'hostname' and 'addresses' (a list of IP addresses).
- `warnings`: A list of MX resolution warnings.

If a DNS error occurs, the dictionary will contain:
- `hosts`: An empty list.
- `error`: An error message string.

### Return Type
`MXResultsSuccess` or `MXResultsFailure`
```

--------------------------------

### checkdmarc.smtp.get_mx_hosts

Source: https://github.com/domainaware/checkdmarc/blob/main/docs/source/api.md

Retrieves MX hostnames and their associated IP addresses for a given domain. Supports TLS skipping, approved hostnames filtering, MTA-STS pattern matching, and parked domain detection.

```APIDOC
## checkdmarc.smtp.get_mx_hosts

### Description
Gets MX hostname and their addresses for a given domain.

### Method
Not applicable (Python function)

### Endpoint
Not applicable (Python function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **domain** (*str*) – A domain name
* **skip_tls** (*bool*) – Skip STARTTLS testing (Optional, default: False)
* **approved_hostnames** (*list[str]*) – A list of approved MX hostname substrings (Optional, default: None)
* **mta_sts_mx_patterns** (*list[str]*) – A list of MX patterns from MTA-STS (Optional, default: None)
* **parked** (*bool*) – Indicates that the domains are parked (Optional, default: False)
* **nameservers** (*Sequence[str | Nameserver]*) – A list of nameservers to query (Optional, default: None)
* **resolver** (*Resolver*) – A resolver object to use for DNS requests (Optional, default: None)
* **timeout** (*float*) – number of seconds to wait for a record from DNS (Optional, default: 2.0)
* **retries** (*int*) – The number of times to retry on timeout or other transient errors (Optional, default: 0)

### Response
#### Success Response
Returns a dictionary with the following keys:
- `hosts` - A list of dictionaries, each containing:
  - `hostname` (str) - A hostname
  - `dnssec` (bool) - DNSSEC status
  - `addresses` (list[str]) - A list of IP addresses
  - `tlsa` (list) - A list of TLSA records, if they exist
- `warnings` - A list of MX resolution warnings (list[str])

#### Response Example
{
  "hosts": [
    {
      "hostname": "mail.example.com",
      "dnssec": true,
      "addresses": ["192.0.2.1"],
      "tlsa": []
    }
  ],
  "warnings": []
}

#### Error Response
None explicitly documented.
```

--------------------------------

### checkdmarc.utils.get_soa_record

Source: https://github.com/domainaware/checkdmarc/blob/main/docs/source/api.md

Queries DNS for an SOA record.

```APIDOC
## checkdmarc.utils.get_soa_record

### Description
Queries DNS for an SOA record.

### Parameters
* **domain** (*str*) – A domain name
* **nameservers** (*list*) – A list of nameservers to query
* **resolver** (*dns.resolver.Resolver*) – A resolver object to use for DNS requests
* **timeout** (*float*) – number of seconds to wait for an answer from DNS
* **retries** (*int*) – The number of times to retry on timeout or other transient errors

### Returns
An SOA record

### Return type
str

### Raises
**checkdmarc.DNSException** –
```

--------------------------------

### checkdmarc.utils.normalize_domain

Source: https://github.com/domainaware/checkdmarc/blob/main/docs/source/api.md

Normalize an input domain by removing zero-width characters and lowering it.

```APIDOC
## checkdmarc.utils.normalize_domain

### Description
Normalize an input domain by removing zero-width characters and lowering it.

### Parameters
* **domain** (*str*) – A domain or subdomain

### Returns
A normalized domain

### Return type
str
```

--------------------------------

### checkdmarc.spf.ptr_match

Source: https://github.com/domainaware/checkdmarc/blob/main/docs/source/api.md

Performs a PTR mechanism check to determine if an IP address matches a given domain.

```APIDOC
## checkdmarc.spf.ptr_match(ip_address: str, domain: str, nameservers: Sequence[str | Nameserver] | None = None, resolver: Resolver | None = None, timeout: float = 2.0, retries: int = 0) -> bool

### Description
Preforms a ptr mechanism check.

### Parameters
#### Path Parameters
* **ip_address** (str) - Required - The IP address to check
* **domain** (str) - Required - A domain name
* **nameservers** (list) - Optional - A list of nameservers to query
* **resolver** (dns.resolver.Resolver) - Optional - A resolver object to use for DNS requests
* **timeout** (float) - Optional - number of seconds to wait for an answer from DNS
* **retries** (int) - Optional - The number of times to retry on timeout or other transient errors

### Returns
The result of the check

### Return type
bool

### Raises
* **checkdmarc.DNSException**
```

--------------------------------

### check_mta_sts

Source: https://github.com/domainaware/checkdmarc/blob/main/docs/source/api.md

Checks a domain's MTA-STS policy and returns a dictionary with the parsed policy or an error.

```APIDOC
## check_mta_sts

### Description
Returns a dictionary with a parsed MTA-STS policy or an error.

### Method
check_mta_sts

### Parameters
#### Path Parameters
- **domain** (str) - Required - A domain name
- **nameservers** (list) - Optional - A list of nameservers to query
- **resolver** (dns.resolver.Resolver) - Optional - A resolver object to use for DNS requests
- **timeout** (float) - Optional - number of seconds to wait for an answer from DNS (default: 2.0)
- **retries** (int) - Optional - The number of times to retry on timeout or other transient errors (default: 0)

### Returns
- **Success**: a `dict` with the following keys:
  - `id` (str) - The SIS-MTA DNS record ID
  - `policy` (dict) - The parsed MTA-STS policy
  - `valid` (bool) - True
  - `warnings` (list) - A `list` of warnings
- **Failure**: a `dict` with the following keys:
  - `error` (str) - The error message
  - `valid` (bool) - False
```

--------------------------------

### checkdmarc.dnssec.test_dnssec

Source: https://github.com/domainaware/checkdmarc/blob/main/docs/source/api.md

Checks for DNSSEC support on the given domain.

```APIDOC
## checkdmarc.dnssec.test_dnssec

### Description
Check for DNSSEC on the given domain.

### Parameters
* **domain** (*str*) – The domain to check
* **nameservers** (*list*) – A list of nameservers to query
* **timeout** (*float*) – Timeout in seconds
* **cache** (*ExpiringDict*) – Cache

### Returns
DNSSEC status.

### Return type
bool
```

--------------------------------

### get_certificate_metadata

Source: https://github.com/domainaware/checkdmarc/blob/main/docs/source/api.md

Retrieves metadata about a Verified Mark Certificate (VMC) from its PEM encoded certificate.

```APIDOC
## get_certificate_metadata(pem_crt: bytes, domain=None) -> dict[str, Any]

### Description
Get metadata about a Verified Mark Certificate (VMC).

### Parameters
#### Required Parameters
- **pem_crt** (bytes) - The PEM encoded certificate.

#### Optional Parameters
- **domain** (str | None) - The domain name associated with the certificate.

### Returns
- **dict[str, Any]** - A dictionary containing the certificate metadata.
```

--------------------------------

### checkdmarc.utils.get_mx_records

Source: https://github.com/domainaware/checkdmarc/blob/main/docs/source/api.md

Queries DNS for a list of Mail Exchange hosts for a given domain.

```APIDOC
## checkdmarc.utils.get_mx_records

### Description
Queries DNS for a list of Mail Exchange hosts.

### Parameters
* **domain** (*str*) – A domain name
* **nameservers** (*list*) – A list of nameservers to query
* **resolver** (*dns.resolver.Resolver*) – A resolver object to use for DNS requests
* **timeout** (*float*) – number of seconds to wait for an answer from DNS
* **retries** (*int*) – The number of times to retry on timeout or other transient errors

### Returns
A list of `dicts`; each containing a `preference` integer and a `hostname`.

### Return type
list

### Raises
**checkdmarc.DNSException** –
```

--------------------------------

### output_to_file

Source: https://github.com/domainaware/checkdmarc/blob/main/docs/source/api.md

Writes the provided content to a specified file path. Supports JSON or CSV formatted content.

```APIDOC
## output_to_file

### Description
Write given content to the given path.

### Method
checkdmarc.output_to_file

### Parameters
#### Path Parameters
- **path** (str) - Required - A file path
- **content** (str) - Required - JSON or CSV text
```

--------------------------------

### mx_in_mta_sts_patterns

Source: https://github.com/domainaware/checkdmarc/blob/main/docs/source/api.md

Tests if a given MX hostname is covered by a list of MTA-STS policy MX patterns.

```APIDOC
## mx_in_mta_sts_patterns

### Description
Tests if a given MX hostname is covered by a given list of MX patterns from an MTA-STS policy.

### Method
mx_in_mta_sts_patterns

### Parameters
#### Path Parameters
- **mx_hostname** (str) - Required - The MX hostname to test
- **mta_sts_mx_patterns** (list[str]) - Required - The list of MTA-STS MX patterns

### Returns
- **Success**: bool - True if the MX hostname is included, False otherwise.
```

--------------------------------

### checkdmarc.smtp.test_tls

Source: https://github.com/domainaware/checkdmarc/blob/main/docs/source/api.md

Attempts to connect to an SMTP server on port 465 and validates TLS/SSL support.

```APIDOC
## checkdmarc.smtp.test_tls

### Description
Attempt to connect to an SMTP server port 465 and validate TLS/SSL support.

### Method
Not applicable (Python function)

### Endpoint
Not applicable (Python function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **hostname** (*str*) – The hostname
* **ssl_context** (*SSLContext*) – A SSL context (Optional, default: None)
* **cache** (*ExpiringDict*) – Cache storage (Optional, default: None)
* **timeout** (*float*) – number of seconds to wait for a connection (Optional, default: 5.0)

### Response
#### Success Response
Returns `True` if TLS is supported.

#### Response Example
```
True
```

#### Error Response
* **checkdmarc.smtp.SMTPError** – SMTP connection failed.
```

--------------------------------

### parse_mta_sts_policy

Source: https://github.com/domainaware/checkdmarc/blob/main/docs/source/api.md

Parses an MTA-STS policy string into a structured format.

```APIDOC
## parse_mta_sts_policy

### Description
Parses an MTA-STS policy.

### Method
parse_mta_sts_policy

### Parameters
#### Path Parameters
- **policy** (str) - Required - The policy string to parse

### Raises
- **checkdmarc.mta_sts.MTASTSPolicySyntaxError** - If the policy has a syntax error.
```

--------------------------------

### checkdmarc.utils.get_reverse_dns

Source: https://github.com/domainaware/checkdmarc/blob/main/docs/source/api.md

Queries for an IP addresses reverse DNS hostname(s).

```APIDOC
## checkdmarc.utils.get_reverse_dns

### Description
Queries for an IP addresses reverse DNS hostname(s).

### Parameters
* **ip_address** (*str*) – An IPv4 or IPv6 address
* **nameservers** (*list*) – A list of nameservers to query
* **resolver** (*dns.resolver.Resolver*) – A resolver object to use for DNS requests
* **timeout** (*float*) – number of seconds to wait for an answer from DNS
* **retries** (*int*) – The number of times to retry on timeout or other transient errors

### Returns
A list of reverse DNS hostnames

### Return type
list

### Raises
**checkdmarc.DNSException** –
```

--------------------------------

### checkdmarc.utils.get_a_records

Source: https://github.com/domainaware/checkdmarc/blob/main/docs/source/api.md

Queries DNS for A and AAAA records for a given domain. Returns a sorted list of IPv4 and IPv6 addresses.

```APIDOC
## checkdmarc.utils.get_a_records(domain: str, nameservers: Sequence[str | Nameserver] | None = None, resolver: Resolver | None = None, timeout: float = 2.0, retries: int = 0) -> list[str]

### Description
Queries DNS for A and AAAA records

### Parameters
#### Path Parameters
* **domain** (str) - Required - A domain name
* **nameservers** (list) - Optional - A list of nameservers to query
* **resolver** (dns.resolver.Resolver) - Optional - A resolver object to use for DNS requests
* **timeout** (float) - Optional - number of seconds to wait for an answer from DNS
* **retries** (int) - Optional - The number of times to retry on timeout or other transient errors

### Returns
A sorted list of IPv4 and IPv6 addresses

### Return type
list

### Raises
* **checkdmarc.DNSException**
```

--------------------------------

### checkdmarc.dnssec.get_dnskey

Source: https://github.com/domainaware/checkdmarc/blob/main/docs/source/api.md

Retrieves the DNSKEY RRSet for a given domain.

```APIDOC
## checkdmarc.dnssec.get_dnskey

### Description
Get a DNSKEY RRSet on the given domain.

### Parameters
* **domain** (*str*) – The domain to check
* **nameservers** (*list*) – A list of nameservers to query
* **timeout** (*float*) – Timeout in seconds
* **cache** (*ExpiringDict*) – A cache

### Returns
A DNSKEY dictionary if a DNSKEY is found.

### Return type
dict | None
```

--------------------------------

### query_smtp_tls_reporting_record

Source: https://github.com/domainaware/checkdmarc/blob/main/docs/source/api.md

Queries DNS for an SMTP TLS Reporting record for a specified domain.

```APIDOC
## query_smtp_tls_reporting_record

### Description
Queries the Domain Name System (DNS) for an SMTP TLS Reporting (TLR) record associated with a given domain. Allows specifying nameservers, a custom resolver, timeout, and retry attempts.

### Method
`checkdmarc.smtp_tls_reporting.query_smtp_tls_reporting_record`

### Parameters
#### Path Parameters
- **domain** (str) - Required - The domain name to query for the TLR record.
- **nameservers** (Sequence[str | Nameserver]) - Optional - A list of nameservers to use for the query. Defaults to None.
- **resolver** (Resolver) - Optional - A `dns.resolver.Resolver` object to use for DNS requests. Defaults to None.
- **timeout** (float) - Optional - The number of seconds to wait for a response from the DNS server. Defaults to 2.0.
- **retries** (int) - Optional - The number of times to retry the query in case of timeouts or transient errors. Defaults to 0.

### Returns
A dictionary containing the 'record' (the unparsed SMTP TLS Reporting record string) and 'warnings' (a list of any warning conditions encountered during the query).

### Raises
- `checkdmarc.smtp_tls_reporting.SMTPTLSReportingRecordNotFound`
- `checkdmarc.smtp_tls_reporting.SMTPTLSReportingRecordInWrongLocation`
- `checkdmarc.smtp_tls_reporting.MultipleSMTPTLSReportingRecords`
```