Reimar/email-dns-tools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add SPF macro guide

Browse Source
This commit is contained in:
Reimar 2026-01-15 14:57:25 +01:00
parent 5b8a3d9266
commit 0276828a2c
Signed by: Reimar
GPG Key ID: 93549FA07F0AE268
4 changed files with 168 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
assets/styles/main.css
View File

@ -75,6 +75,20 @@ a {
color: #039BE5;
}
code {
font-family: "JetBrains Mono", monospace;
background-color: #EEE;
border-radius: 3px;
padding: 0 0.25rem;
}
blockquote {
color: #757575;
padding-left: 1rem;
margin-left: 1rem;
border-left: 2px solid #EEE;
}
hr {
border: none;
border-bottom: 1px solid #BDBDBD;

4
spf-creator/index.html
View File

@ -45,9 +45,7 @@
<p>
For advanced usage, domain fields may contain macros. These start with a percentage sign and will expand
to a dynamic value. For example, <b>%{d}</b> expands to the current domain and <b>%{i}</b> to the
current IP address. See
<a href="https://www.rfc-editor.org/rfc/rfc7208#section-7.2" target="_blank">the SPF specification</a>
for a list of macros you can use.
current IP address. See the <a href="/spf-macro-guide">Macro Guide</a> for a list of all macros.
</p>
<center>

152
spf-macro-guide/index.html Normal file
View File

@ -0,0 +1,152 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>SPF Macro Guide - Explanation of all SPF macros with examples</title>
<link rel="stylesheet" href="/assets/styles/main.css">
<script type="module" src="/assets/scripts/ui/validator.js"></script>
</head>
<body>
<h1>SPF Macro Guide</h1>
<main>
<h2>Overview of SPF macros</h2>
<p>
Using SPF, you can specify which IP addresses are authorized to send emails from a mail server.
Many of the directives you can use allow you to specify a domain name, but here SPF comes with an
extra feature: Macros.
</p>
<p>
Macros allow you to insert dynamic values into the values of SPF directives, which can be used for
e.g. per-user authentication and more. This guide will go through all macros, along with some examples.
</p>
<p>
The mechanisms and modifiers that allow macros are: <b>include</b>, <b>a</b>, <b>mx</b>, <b>ptr</b>,
<b>exists</b>, <b>redirect</b> and <b>exp</b>.
</p>
<h3>List of macros</h3>
<ul>
<li>
<p><code>%{s}</code> - Sender email address</p>
<p>Expands to the email address which the current email is being sent from, e.g. <code>john@example.com</code></p>
</li>
<li>
<p><code>%{o}</code> - Sender domain</p>
<p>Expands to only the domain part of the sender email address, e.g. <code>example.com</code></p>
</li>
<li>
<p><code>%{l}</code> - Sender username</p>
<p>Expands to only the local part of the sender email address, e.g. <code>john</code></p>
</li>
<li>
<p><code>%{d}</code> - Current domain</p>
<p>
This starts out identical to the sender domain, but when hitting an <b>include</b> mechanism or
a <b>redirect</b> modifier, this value will change to the domain specified in that term
during the processing of it.
</p>
</li>
<li>
<p><code>%{i}</code> - IP address</p>
<p>
Expands to the IP address of the email client that is sending the mail.
This can both be an IPv4 and IPv6 address.
</p>
</li>
<li>
<p><code>%{v}</code> - IP version</p>
</li>
<li>
<p>Expands to the string <b>"in-addr"</b> if the sender address is IPv4, or <b>"ip6"</b> if it is IPv6.</p>
</li>
<li>
<p><code>%{p}</code> - Validated domain name</p>
<p>
Does a reverse DNS lookup of the sender IP address, and validates that the resulting domain
is a subdomain of the current domain. Expands to the validated domain, or the string "unknown".
<b>NOTE:</b> It is not recommended to use this macro. From the specification:
</p>
<blockquote>
This mechanism is slow, it is not as reliable as other
mechanisms in cases of DNS errors, and it places a large burden on
the .arpa name servers. If used, proper PTR records have to be in
place for the domain's hosts and the "ptr" mechanism SHOULD be one of
the last mechanisms checked. After many years of SPF deployment
experience, it has been concluded that it is unnecessary and more
reliable alternatives should be used instead.
</blockquote>
</li>
<li>
<p><code>%{h}</code> - HELO/EHLO domain</p>
<p>Expands to the domain given on the SMTP HELO/EHLO commands.</p>
</li>
</ul>
<h3>Transformers</h3>
<p>SPF macros can be transformed in a few different ways, by adding another character after the macro letter.</p>
<ul>
<li>
<p>Reverse transformer (r)</p>
<p>
Adding "r" after a macro will reverse the domain name or IP address.
E.g. if <code>%{d}</code> expands to <b>example.com</b>, <code>%{dr}</code> will be
<b>com.example</b>.
Likewise, if <code>%{i}</code> expands to <b>192.0.2.1</b>, <code>%{ir}</code> will become
<b>1.2.0.192</b>.
</p>
</li>
<li>
<p>Digit transformer (1-9)</p>
<p>
Adding a number after a macro, will take that amount of right-hand parts of the domain name /
IP address. This may be combined with reversing. E.g. for the domain <b>mail.example.com</b>,
<code>%{d2}</code> will expand to <b>example.com</b>.
</p>
</li>
</ul>
<h3>Explanations</h3>
<p>
SPF allows you to set custom error messages in case of failed validations using the <b>exp</b> modifier.
The message is retrieved from the TXT records of the domain name defined by the modifier.
This error message also supports macros, and has extended support for a few more than the ones above:
</p>
<ul>
<li>
<p><code>{%c}</code> - SMTP client IP (easily readable format)</p>
</li>
<li>
<p><code>{%r}</code> - Domain name of host performing the check</p>
</li>
<li>
<p><code>{%t}</code> - Current timestamp</p>
</li>
</ul>
<center>
<h3>SPF tools:</h3>
<a href="/spf-validator">SPF Validator Tool</a> &bull;
<a href="/spf-creator">SPF Creator Tool</a>
</center>
</main>
</body>
</html>

2
spf-validator/index.html
View File

@ -64,7 +64,7 @@
<center>
<h3>More tools:</h3>
<a href="/dmarc-validator">DMARC Validator Tool</a>
<a href="/spf-creator">SPF Creator Tool</a>
</center>
</main>
</body>