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