djblets.mail.dmarc¶
Functions for looking up DMARC entries in DNS.
- class DmarcPolicy(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)¶
Bases:
Enum
Types of DMARC policies.
These policies define what happens if an e-mail fails sender verification (such as if the From address is spoofed).
- NONE = 1¶
No action should be taken if verification fails.
E-mails will not be rejected or quarantined, and the DMARC signature can be ignored.
- QUARANTINE = 2¶
E-mails should be quarantined/marked as spam if verification fails.
- REJECT = 3¶
E-mails should be rejected if verification fails.
- classmethod parse(policy_str: str) DmarcPolicy ¶
Return a policy type from a value in a DMARC record.
- class DmarcRecord(*, hostname: str, policy: DmarcPolicy, subdomain_policy: DmarcPolicy = DmarcPolicy.UNSET, pct: int = 100, fields: Dict[str, str] = {})¶
Bases:
object
Information on a DMARC record for a subdomain or organization domain.
This is a parsed representation of the contents of a standard DMARC TXT record. It contains information that software can use to determine what will happen if a sender spoofs a From address, or if the e-mail otherwise fails sender verification.
Senders can make use of this to determine whether they can safely spoof a From address (for legitimate reasons, such as to send an e-mail on behalf of a user when posting on a service), or whether they should fall back to an alternative means (such as using a noreply address and setting the Reply-To header).
- __init__(*, hostname: str, policy: DmarcPolicy, subdomain_policy: DmarcPolicy = DmarcPolicy.UNSET, pct: int = 100, fields: Dict[str, str] = {}) None ¶
Initialize the record.
- Parameters:
hostname (
str
) – The hostname containing the_dmarc.
TXT record.policy (
int
) – The sender policy defined for the record.subdomain_policy (
int
, optional) – The sender policy defined for subdomains on this domain.pct (
int
, optional) – The percentage (as a number from 0-100) of e-mails that should be subject to the sender policy.fields (
dict
, optional) – Additional fields from the record.
- policy: DmarcPolicy¶
The sender policy defined for the record.
- Type:
- subdomain_policy: DmarcPolicy¶
The sender policy defined for subdomains on this domain.
- Type:
- pct: int¶
The percentage of e-mails that should be subject to the sender policy.
This is a range between 0 and 100.
- Type:
- __annotations__ = {'fields': 'Dict[str, str]', 'hostname': 'str', 'pct': 'int', 'policy': 'DmarcPolicy', 'subdomain_policy': 'DmarcPolicy'}¶
- __eq__(other: object) bool ¶
Return whether two records are equal.
Records are considered equal if they have the same
hostname
andfields
.- Parameters:
other (
DmarcRecord
) – The record to compare to.- Returns:
True
if the two records are equal.False
if they are not.- Return type:
- __hash__ = None¶
- classmethod parse(hostname: str, txt_record: str) Optional[DmarcRecord] ¶
Return a DmarcRecord from a DMARC TXT record.
- Parameters:
- Returns:
The parsed record, if this is a valid DMARC record. If this is not valid,
None
will be returned instead.- Return type:
- get_dmarc_record(hostname: str, use_cache: bool = True, cache_expiration: int = 2592000) Optional[DmarcRecord] ¶
Return a DMARC record for a given hostname.
This will query the DNS records for a hostname, returning a parsed version of the DMARC record, if found. If a record could not be found for the hostname, the organizational domain will be used instead (which is generally example.com for foo.bar.example.com, but this depends on the domain in question).
By default, the fetched record from DNS is cached, allowing this to be called multiple times without repeated DNS queries. This is optional, as is the expiration time for the cached data (which defaults to 1 month).
- Parameters:
- Returns:
The DMARC record. If it could not be found,
None
will be returned instead.- Return type:
- is_email_allowed_by_dmarc(email_address: str) bool ¶
Return whether DMARC rules safely allow sending using an e-mail address.
This will take an e-mail address (which must be in the form of
name@domain
, ideally parsed bymail.utils.parseaddr()
) and check to see if there are any DMARC rules that could prevent the e-mail from being sent/received if it were to fail sender verification.Callers can use this to decide whether they can safely send using a user’s e-mail address, or whether they need to send using the service’s address.