SPF macros are placeholders within an SPF record (e.g., %{i} , %{s} ) that dynamically expand to specific values (like the sender's IP address or email) when a receiving mail server processes an email. They offer flexibility for domains with complex sending infrastructures.

Why would I use SPF macros?

Macros help bypass the SPF 10-DNS lookup limit by allowing a single record to dynamically authorize many sending IPs or domains without listing each explicitly. This is particularly useful for organizations using numerous third-party email services or having highly dynamic IP ranges.

How do I check SPF macro values?

You cannot statically "check" the expanded values of SPF macros because they are resolved in real-time by the receiving mail server during email authentication. However, you can use DNS lookup tools like dig to verify the syntax and presence of the macros within your raw SPF TXT record.

Are there any downsides to using SPF macros?

While macros offer flexibility, they can complicate troubleshooting due to their dynamic nature. Misconfigurations can lead to authentication failures. For simpler setups, the complexity might outweigh the benefits, making direct IP or include mechanisms a more straightforward approach.

How to check SPF macro values and how do they work? - Technical - Email deliverability - Knowledge base

SPF (Sender Policy Framework) is a crucial email authentication method that helps prevent spoofing by allowing domain owners to specify which mail servers are authorized to send email on their behalf. While SPF records primarily list IP addresses and sending domains, they also support a powerful feature called SPF macros. These macros introduce dynamic flexibility to your SPF records.

Macros enable the SPF record to expand to different values based on the context of the email being sent, such as the sender's IP address or the recipient's domain. This dynamic capability can be incredibly useful for organizations that send email through various services or have complex sending infrastructures. However, understanding how these macros work and how to effectively check their values can be a bit intricate due to their dynamic nature.

Suped DMARC monitoring

Free forever, no credit card required

Learn more

Trusted by teams securing millions of inboxes

What are SPF macros?

SPF macros are special placeholders within an SPF record that expand to specific values at the time of an email's reception and verification. They are identified by a percent (%) sign followed by a single letter or character enclosed in curly braces, like %{i} or %{s}. This mechanism allows for a single SPF record to adapt to various sending scenarios without requiring constant manual updates to the DNS record itself.

The primary motivation behind using SPF macros is to provide greater flexibility and to help manage the often-cited 10-DNS lookup limit. Without macros, each authorized sending source (like a third-party email service provider or an internal mail server) might require a separate include mechanism, quickly exhausting the lookup limit, which can lead to SPF validation failures. Macros offer a way to create more concise and dynamic records that can handle a wider array of sending IPs without hitting this ceiling. There are also specific reasons to avoid SPF macros in certain situations.

For example, an SPF record might use a macro to include an IP address derived from the connecting IP of the sending server or to insert the local part of the sender's email address. This dynamic substitution ensures that the SPF check is performed against the most relevant and precise information at the moment of evaluation, making email authentication more adaptable and efficient. For a general overview of email authentication, read about how SPF, DKIM, and DMARC work together.

How SPF macros work

When a receiving mail server performs an SPF check on an incoming email, it first retrieves the sender's SPF record from DNS. If that record contains SPF macros, the receiving server then substitutes these placeholders with actual values extracted from the email message's metadata or the connection context. This expansion happens in real time, during the authentication process. You can find the full form of SPF in email within its specification.

The SPF specification, detailed in RFC 7208, outlines the various macro characters and how they should be expanded. For instance, the %{i} macro expands to the IP address of the client that connected to the mail server, while %{s} expands to the sender's email address. The expanded value is then used in conjunction with other SPF mechanisms (like a, mx, ptr, ip4, ip6, exists) to determine if the sending server is authorized.

Macro	Expansion value
%{s}	The sender email address.
%{l}	The local part of the sender address.
%{o}	The domain part of the sender address.
%{d}	The current domain being checked.
%{i}	The IP address of the client.
%{h}	The HELO/EHLO domain.
%{r}	The receiving domain.
%{t}	Current timestamp.

Consider this example SPF record using a macro:

SPF record example with a macroDNS

v=spf1 ip4:192.0.2.1 exists:%{i}.%{d}.spf.example.com -all

This record tells a receiving server to check if the connecting IP address, along with the current domain, resolves within spf.example.com. This kind of dynamic lookup allows for advanced configurations, such as verifying that the sender's IP is listed on a specific internal blocklist or a dynamic IP range managed by a third party. To understand more about SPF, DKIM, and DMARC, refer to a simple guide to DMARC, SPF, and DKIM.

Checking SPF macro values

It's important to clarify that you don't "check" SPF macro values in the same way you would a static IP address in a DNS record. Since macros are placeholders that expand dynamically based on the email's context, their "value" isn't fixed until an email is actually processed by a receiving mail server. What you can check is the syntax of your SPF record and ensure the macro is correctly formatted. You can use an online SPF checker to validate your record syntax.

To verify your SPF record's syntax and presence, you can use DNS lookup tools. On a Unix or macOS system, the dig command is a reliable way to retrieve your domain's TXT records, where your SPF record resides. Simply run dig yourdomain.com TXT in your terminal. This will show you the raw SPF record, including any macros you have defined. This process helps with validating your SPF records.

Understanding dynamic expansion

It's a common misunderstanding to think that SPF macro values are stored somewhere on the domain. They are not. As per the official Sender Policy Framework (SPF) RFC 7208 specification, the values for macros are derived directly from the email message and its connection attributes during the actual email authentication process. This dynamic behavior makes static checks of the expanded values impossible before an email is sent.

Troubleshooting macro-related issues

When evaluating an SPF record that uses macros, online SPF checkers or validation tools may indicate the presence of macros but won't typically show their expanded values, as these depend on the specific email transaction. This is why understanding the mechanism behind macros is key. Focusing on proper SPF record syntax and the logic of your macro expressions is more crucial than trying to predict specific expanded values. If you're encountering TempError issues, it could be related to complex SPF records with macros, indicating a DNS lookup problem during evaluation. You can learn more about this by reading about demystifying the SPF TempError in your DMARC reports.

Advanced considerations for SPF macros

While SPF macros offer significant advantages, particularly for large-scale senders or those using complex email infrastructures, they also introduce a layer of complexity that can lead to misconfigurations. One of the main reasons organizations choose to implement SPF macros is to get around the SPF 10-DNS lookup limit. This limit is imposed by the SPF specification to prevent excessive DNS queries during email validation. When an SPF record exceeds this limit, receiving mail servers may treat the SPF check as a PermError or TempError, potentially leading to emails being rejected or sent to spam. This is also a common cause of issues like SPF DNS timeout errors with Microsoft services. For more on the function of SPF, read this article on SPF macros explained.

Without SPF macros

DNS lookups: Can quickly hit the 10-DNS lookup limit with many include mechanisms.
Record maintenance: Requires manual updates to the SPF record every time an IP address or sending service changes.
Flexibility: Limited flexibility; records are static and can be cumbersome for diverse sending environments.
Scalability: Poor scalability for rapidly changing or large numbers of sending IPs.

With SPF macros

DNS lookups: Helps to stay within the 10-DNS lookup limit by dynamically resolving sender IPs.
Record maintenance: Automated or dynamic resolution reduces manual intervention, especially for large infrastructures.
Flexibility: High flexibility; adapts to different sending contexts without needing multiple static records.
Scalability: Excellent scalability for managing a wide range of sending sources.

The key takeaway is that while macros can be a powerful tool for sophisticated email setups, they demand a deeper understanding of the SPF specification and careful implementation to avoid potential email deliverability issues. Understanding SPF authentication and alignment is crucial for effective use of macros.

Views from the trenches

Best practices

Keep your SPF record concise and efficient to prevent hitting the 10-DNS lookup limit, crucial for optimal deliverability.

Test SPF records rigorously using tools that parse macros correctly, ensuring dynamic values behave as intended.

Document your SPF macro usage, including expansion logic, to aid future troubleshooting and collaboration.

Common pitfalls

Over-complicating SPF records with unnecessary macros can lead to syntax errors and validation failures, impacting deliverability.

Failing to account for all possible dynamic expansions may result in legitimate emails being flagged as unauthorized.

Not regularly auditing your SPF record for changes in sending infrastructure can cause outdated and ineffective policies.

Expert tips

Prioritize simplicity in SPF records unless dynamic flexibility from macros is strictly necessary.

Use macros for large, dynamic sending environments where static includes are impractical or exceed lookup limits.

Regularly monitor DMARC reports to identify any SPF authentication failures potentially caused by macro misconfigurations.

Marketer view

Marketer from Email Geeks says they use dig multiple times every day for DNS queries from their Mac terminal and found macros mind blowing.

2019-05-07 - Email Geeks

Expert view

Expert from Email Geeks says that some tools don't properly handle SPF macros and may fail ungracefully, so it's important to understand the underlying mechanism.

2019-05-08 - Email Geeks

The dynamic power of SPF macros

SPF macros are an advanced feature that brings dynamic capabilities to your email authentication, allowing your SPF records to adapt to various sending scenarios in real time. While they aren't directly "checked" in a static sense, understanding their expansion logic and verifying the syntax of your SPF record are essential steps in ensuring proper email deliverability. For organizations with complex sending environments, macros can be an indispensable tool for maintaining a robust email security posture.