--- name: "spfquery" section: "1p" platform: "linux" package: "perl-mail-spf" version: "3.20260331-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/spfquery/1p" --- # spfquery(1p) (Mail::SPF) - Checks if a given set of e-mail parameters matches a domain's SPF policy ## NAME spfquery - (Mail::SPF) - Checks if a given set of e-mail parameters matches a domain's SPF policy ## VERSION version 3.20260331 ## SYNOPSIS - **Preferred usage:** **spfquery** \[**--versions**\|**-v** **1**\|**2**\|**1,2**\] \[**--scope**\|**-s** **helo**\|**mfrom**\|**pra**\] **--identity**\|**--id** *identity* **--ip-address**\|**--ip** *ip-address* \[**--helo-identity**\|**--helo-id** *helo-identity*\] \[*OPTIONS*\] **spfquery** \[**--versions**\|**-v** **1**\|**2**\|**1,2**\] \[**--scope**\|**-s** **helo**\|**mfrom**\|**pra**\] **--file**\|**-f** *filename*\|**-** \[*OPTIONS*\] - **Legacy usage:** **spfquery** **--helo** *helo-identity* **--ip-address**\|**--ip** *ip-address* \[*OPTIONS*\] **spfquery** **--mfrom** *mfrom-identity* **--ip-address**\|**--ip** *ip-address* \[**--helo** *helo-identity*\] \[*OPTIONS*\] **spfquery** **--pra** *pra-identity* **--ip-address**\|**--ip** *ip-address* \[*OPTIONS*\] - **Other usage:** **spfquery** **--version**\|**-V** **spfquery** **--help** ## DESCRIPTION **spfquery** checks if a given set of e-mail parameters (e.g. the SMTP sender's IP address) matches the responsible domain's Sender Policy Framework (SPF) policy. For more information on SPF see \. ### Preferred Usage The following usage forms are preferred over the legacy forms used by older **spfquery** versions: The **--identity** form checks if the given *ip-address* is an authorized SMTP sender for the given `"helo"` hostname, `"mfrom"` envelope sender e-mail address, or `"pra"` (so-called purported resonsible address) e-mail address, depending on the value of the **--scope** option (which defaults to **mfrom** if omitted). The **--file** form reads "*ip-address* *identity* \[*helo-identity*\]" tuples from the file with the specified *filename*, or from standard input if *filename* is **-**, and checks them against the specified scope (**mfrom** by default). Both forms support an optional **--versions** option, which specifies a comma-separated list of the SPF version numbers of SPF records that may be used. **1** means that `"v=spf1"` records should be used. **2** means that `"spf2.0"` records should be used. Defaults to **1,2**, i.e., uses any SPF records that are available. Records of a higher version are preferred. ### Legacy Usage **spfquery** versions before 2.500 featured the following usage forms, which are discouraged but still supported for backwards compatibility: The **--helo** form checks if the given *ip-address* is an authorized SMTP sender for the `"HELO"` hostname given as the *identity* (so-called `"HELO"` check). The **--mfrom** form checks if the given *ip-address* is an authorized SMTP sender for the envelope sender email-address (or domain) given as the *identity* (so-called `"MAIL FROM"` check). If a domain is given instead of an e-mail address, `"postmaster"` will be substituted for the localpart. The **--pra** form checks if the given *ip-address* is an authorized SMTP sender for the PRA (Purported Responsible Address) e-mail address given as the identity. ### Other Usage The **--version** form prints version information of spfquery. The **--help** form prints usage information for spfquery. ## OPTIONS ### Standard Options The preferred and legacy forms optionally take any of the following *OPTIONS*: - **--default-explanation** *string* - **--def-exp** *string* Use the specified *string* as the default explanation if the authority domain does not specify an explanation string of its own. - **--hostname** *hostname* Use *hostname* as the host name of the local system instead of auto-detecting it. - **--keep-comments** - **--no-keep-comments** Do (not) print any comments found when reading from a file or from standard input. - **--sanitize** (currently ignored) - **--no-sanitize** (currently ignored) Do (not) sanitize the output by condensing consecutive white-space into a single space and replacing non-printable characters with question marks. Enabled by default. - **--debug** (currently ignored) Print out debug information. ### Black Magic Options Several options that were supported by earlier versions of **spfquery** are considered black magic (i.e. potentially dangerous for the innocent user) and are thus disabled by default. If the **Mail::SPF::BlackMagic** Perl module is installed (module currently not available), they may be enabled by specifying **--enable-black-magic**. - **--max-dns-interactive-terms** *n* Evaluate a maximum of *n* DNS-interactive mechanisms and modifiers per SPF check. Defaults to **10**. Do *not* override the default unless you know what you are doing! - **--max-name-lookups-per-term** *n* Perform a maximum of *n* DNS name look-ups per mechanism or modifier. Defaults to **10**. Do *not* override the default unless you know what you are doing! - **--authorize-mxes-for** *email-address*\|*domain***,**... Consider all the MXes of the comma-separated list of *email-address*es and *domain*s as inherently authorized. - **--tfwl** Perform `"trusted-forwarder.org"` accreditation checking. - **--guess** *spf-terms* Use *spf-terms* as a default record if no SPF record is found. - **--local** *spf-terms* Process *spf-terms* as local policy before resorting to a default result (the implicit or explicit `"all"` mechanism at the end of the domain's SPF record). For example, this could be used for white-listing one's secondary MXes: `"mx:mydomain.example.org"`. - **--override** *domain***=***spf-record* - **--fallback** *domain***=***spf-record* Set overrides and fallbacks. Each option can be specified multiple times. For example: ``` --override example.org='v=spf1 -all' --override '*.example.net'='v=spf1 a mx -all' --fallback example.com='v=spf1 -all' ``` ## RESULT CODES - **pass** The specified IP address is an authorized SMTP sender for the identity. - **fail** The specified IP address is not an authorized SMTP sender for the identity. - **softfail** The specified IP address is not an authorized SMTP sender for the identity, however the authority domain is still testing out its SPF policy. - **neutral** The identity's authority domain makes no assertion about the status of the IP address. - **permerror** A permanent error occurred while evaluating the authority domain's policy (e.g., a syntax error in the SPF record). Manual intervention is required from the authority domain. - **temperror** A temporary error occurred while evaluating the authority domain's policy (e.g., a DNS error). Try again later. - **none** There is no applicable SPF policy for the identity domain. ## EXIT CODES ``` Result | Exit code -----------+----------- pass | 0 fail | 1 softfail | 2 neutral | 3 permerror | 4 temperror | 5 none | 6 ``` ## EXAMPLES ``` spfquery --scope mfrom --id user@example.com --ip 1.2.3.4 spfquery --file test_data echo "127.0.0.1 user@example.com helohost.example.com" | spfquery -f - ``` ## COMPATIBILITY **spfquery** has undergone the following interface changes compared to earlier versions: - **2.500** - • A new preferred usage style for performing individual SPF checks has been introduced. The new style accepts a unified **--identity** option and an optional **--scope** option that specifies the type (scope) of the identity. In contrast, the legacy usage style requires a separate usage form for every supported scope. See "Preferred usage" and "Legacy usage" for details. - • The former `"unknown"` and `"error"` result codes have been renamed to `"permerror"` and `"temperror"`, respectively, in order to comply with RFC 4408 terminology. - • SPF checks with an empty identity are no longer supported. In the case of an empty `"MAIL FROM"` SMTP transaction parameter, perform a check with the `"helo"` scope directly. - • The **--debug** and **--(no-)sanitize** options are currently ignored by this version of **spfquery**. They will again be supported in the future. - • Several features that were supported by earlier versions of **spfquery** are considered black magic and thus are now disabled by default. See "Black Magic Options". - • Several option names have been deprecated. This is a list of them and their preferred synonyms: ``` Deprecated options | Preferred options ---------------------+----------------------------- --sender, -s | --mfrom --ipv4, -i | --ip-address, --ip --name | --hostname --max-lookup-count, | --max-dns-interactive-terms --max-lookup | --rcpt-to, -r | --authorize-mxes-for --trusted | --tfwl ``` ## SEE ALSO Mail::SPF, **spfd**(8) \ ## AUTHORS This version of **spfquery** is a complete rewrite by Julian Mehnle \, based on an earlier version written by Meng Weng Wong \ and Wayne Schlitt \.