From 0276828a2c638d16d8b2ab4e0d70ea7127cf86e4 Mon Sep 17 00:00:00 2001 From: Reimar Date: Thu, 15 Jan 2026 14:57:25 +0100 Subject: [PATCH] Add SPF macro guide --- assets/styles/main.css | 14 ++++ spf-creator/index.html | 4 +- spf-macro-guide/index.html | 152 +++++++++++++++++++++++++++++++++++++ spf-validator/index.html | 2 +- 4 files changed, 168 insertions(+), 4 deletions(-) create mode 100644 spf-macro-guide/index.html diff --git a/assets/styles/main.css b/assets/styles/main.css index a881e6c..69ab909 100644 --- a/assets/styles/main.css +++ b/assets/styles/main.css @@ -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; diff --git a/spf-creator/index.html b/spf-creator/index.html index 8107615..070d360 100644 --- a/spf-creator/index.html +++ b/spf-creator/index.html @@ -45,9 +45,7 @@

For advanced usage, domain fields may contain macros. These start with a percentage sign and will expand to a dynamic value. For example, %{d} expands to the current domain and %{i} to the - current IP address. See - the SPF specification - for a list of macros you can use. + current IP address. See the Macro Guide for a list of all macros.

diff --git a/spf-macro-guide/index.html b/spf-macro-guide/index.html new file mode 100644 index 0000000..3c2248d --- /dev/null +++ b/spf-macro-guide/index.html @@ -0,0 +1,152 @@ + + + + + SPF Macro Guide - Explanation of all SPF macros with examples + + + + +

SPF Macro Guide

+ +
+

Overview of SPF macros

+ +

+ 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. +

+ +

+ 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. +

+ +

+ The mechanisms and modifiers that allow macros are: include, a, mx, ptr, + exists, redirect and exp. +

+ +

List of macros

+ +
    +
  • +

    %{s} - Sender email address

    + +

    Expands to the email address which the current email is being sent from, e.g. john@example.com

    +
    • +
  • +

    %{o} - Sender domain

    + +

    Expands to only the domain part of the sender email address, e.g. example.com

    +
    • +
  • +

    %{l} - Sender username

    + +

    Expands to only the local part of the sender email address, e.g. john

    +
    • +
  • +

    %{d} - Current domain

    + +

    + This starts out identical to the sender domain, but when hitting an include mechanism or + a redirect modifier, this value will change to the domain specified in that term + during the processing of it. +

    +
    • +
  • +

    %{i} - IP address

    + +

    + Expands to the IP address of the email client that is sending the mail. + This can both be an IPv4 and IPv6 address. +

    +
    • +
  • +

    %{v} - IP version

    +
    • +
  • +

    Expands to the string "in-addr" if the sender address is IPv4, or "ip6" if it is IPv6.

    +
    • +
  • +

    %{p} - Validated domain name

    + +

    + 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". + NOTE: It is not recommended to use this macro. From the specification: +

    + +
    + 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. +
    +
    • +
  • +

    %{h} - HELO/EHLO domain

    + +

    Expands to the domain given on the SMTP HELO/EHLO commands.

    +
    • +
+ +

Transformers

+ +

SPF macros can be transformed in a few different ways, by adding another character after the macro letter.

+ +
    +
  • +

    Reverse transformer (r)

    + +

    + Adding "r" after a macro will reverse the domain name or IP address. + E.g. if %{d} expands to example.com, %{dr} will be + com.example. + Likewise, if %{i} expands to 192.0.2.1, %{ir} will become + 1.2.0.192. +

    +
    • +
  • +

    Digit transformer (1-9)

    + +

    + 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 mail.example.com, + %{d2} will expand to example.com. +

    +
    • +
+ +

Explanations

+ +

+ SPF allows you to set custom error messages in case of failed validations using the exp 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: +

+ +
    +
  • +

    {%c} - SMTP client IP (easily readable format)

    +
    • +
  • +

    {%r} - Domain name of host performing the check

    +
    • +
  • +

    {%t} - Current timestamp

    +
    • +
+ +
+

SPF tools:

+ SPF Validator Tool • + SPF Creator Tool +
+
+ + diff --git a/spf-validator/index.html b/spf-validator/index.html index 9342db9..893e360 100644 --- a/spf-validator/index.html +++ b/spf-validator/index.html @@ -64,7 +64,7 @@

More tools:

- DMARC Validator Tool + SPF Creator Tool