Developer’s guide to email headers
They’re the hidden metadata that’s included in the raw email, not visible when simply viewing the message in the inbox. Understanding them can help you troubleshoot sending issues and ensure an overall robust and secure email sending system.
In this article, we’ll go through basic header analysis and demonstrate some practical use cases for better deliverability and an improved email experience. But first, let's start with a quick refresh of the fundamentals.
What are email headers?
An email header (or internet header) provides information about the message in the form of metadata. Some examples include the sender and receiver of the message, IP addresses, the date and time it was received, authentication results, and many more.
They’re crucial for email communication because mailbox providers and ESPs (Email Service Providers) use them to track an email’s delivery route, authenticate the sender, detect phishing or spoofing attempts, and organize messages in the inbox, for example, by creating email threads. Senders can also improve their email experience by customizing certain headers, like a custom unsubscribe header.
Here’s an example of an email message header section:
How to view email headers
Since email header fields aren’t visible within the email message in an inbox, you need to access the message’s raw content. Checking and analyzing these headers during testing and troubleshooting can help you to identify potential issues. Here’s how to do that in some of the most popular email clients:
Gmail
1. Open the email.
2. Click on the More icon (3 dots) in the top right corner, then click Show original.
Yahoo Mail
1. Open the email.
2. Click on the More icon (3 dots) in the top right corner, then click View raw message.
Microsoft Outlook/Hotmail
1. Open the email.
2. Click on the More icon (3 dots) in the top right corner, scroll down to View, then click View message source.
Apple Mail
1. Open the email.
2. Select View in the menu bar at the top of the screen, go to Message, then select All Headers to view the full email header in the app, or Raw Source to view the entire email in a new window.
Types of email headers and examples
There are many mail headers that can be included in a message. Most of them are generated automatically but some can be added or changed to customize the recipient’s email experience. The one thing they have in common is that they all consist of an email header name and value, for example, From: sender@example.com.
Basic email headers
Header | Purpose | Example |
From | Shows the sender’s address. Allows for verification of sender identity and the checking of spoofing attempts | From: Sender Name <sender@example.com> |
To | Shows the recipient’s email address, allowing for correct recipient handling | To: receiver@example.com |
Cc | Shows any carbon copy recipients, can help to debug multi-recipient delivery issues | Cc: colleague@example.com |
Subject | Shows the subject line of the email message, can be parsed for email replies/threading | Subject: Please verify your email address |
Date | Shows the timestamp of when the email was sent, allowing for proper conversation ordering and troubleshooting of time zone issues | Date: 24 Jul 2025 08:39:02 -0000 |
Message-ID | Unique identifier of the email, which is used to organize messages in the inbox and create threads. Can also be used to prevent message duplication and debug delivery issues | Message-ID: <CAOjfHGK7hsdJGLSFqKTFWe-+d3mxLcRP1rXVGw@mail.gmail.com> |
Routing and delivery headers
Header | Purpose | Example |
Received | Logs the journey of the message. This is automatically added every time the email is handled by a mail server. This can be used to trace the delivery path and identify delays | Received: from mail148.mailersend.net (mail148.mailersend.net. [212.11.79.148]) by mx.google.com with ESMTPS id 5l7b17b0944b1-4584986449esi4311235e9.77.2025.07.24.01.39.05 for <receiver@example.com (version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128); Thu, 24 Jul 2025 01:39:05 -0700 (PDT) |
Return-Path | Defines the bounce address for messages that can’t be delivered, allowing you to monitor bounces. This header can be set by the sender or automatically generated by the ESP | Return-Path: <bounce-6z2m8jhgndlsoo6n+6021f1269ee61750ba1b6ab7@mta.mailersend.com> |
Reply-To | This is an optional field that defines where message replies should be sent to. This can be different from the From header, and can be customized by the sender | Reply-To: info@example.com |
Delivered-To | Shows the final recipient of the message | Delivered-To: receiver@example.com |
Authentication and security headers
Header | Purpose | Example |
DKIM-Signature | Defines the cryptographic DKIM signature needed to authenticate the sender, useful for debugging DKIM failures and validating sending sources | DKIM-Signature: a=rsa-sha256; bh=VgcIJg7QXpS4LKAMx35ZtIHdOu2Z/CrUXcIsOHAUckc=; c=relaxed/relaxed; d=mailersend.net; h=X-Mailer-Info:Subject:From:To:Date:Received:Message-ID:X-MailerSend-RecipientID:Feedback-ID:X-MailerSend-MessageID:Reply-To:MIME-Version:Content-Type; s=mlsend; t=1873656342; v=1; b=GkwetdOcnnRXKe0Xa4FetPU4stkwJqXZ+Ma/2qnWHTe0P/9/N8k27+TQBpPrx8UwmtBEdpmd 6TDCjYZaile7To7DQSKW8KhWqgVGGN7r8fjsh7g9kjZdKgxGeF7KUpX7wbe55GnUE9+xhJnnaD HV9pcUAw5D8sqjo2Oz8i1JAg= |
Received-SPF | Shows the result of SPF validation, helps to troubleshoot SPF misconfigurations | Received-SPF: pass (google.com: domain of bounce-7z3m5jghdjsiab9n+6881f1269ee61685ba1b6ab7@mta.mailersend.com designates 211.17.58.138 as permitted sender) client-ip=211.17.58.138; |
Authentication-Results | Shows a summary of SPF, DKIM and DMARC checks so you can quickly debug all authentication checks | Authentication-Results: mx.google.com; dkim=pass header.i=@mailersend.com header.s=mlsend2 header.b=Gv8f5bLD; dkim=pass header.i=@mailersend.net header.s=mlsend header.b=GkwetdOc; spf=pass (google.com: domain of bounce-7z3m5jghdjsiab9n+6881f1269ee61685ba1b6ab7@mta.mailersend.com designates 211.17.58.138 as permitted sender) smtp.mailfrom=bounce-7z3m5jghdjsiab9n+6881f1269ee61685ba1b6ab7@mta.mailersend.com; dmarc=pass (p=REJECT sp=REJECT dis=NONE) header.from=mailersend.com |
Other headers that can be used for troubleshooting
Header | Purpose | Example |
MIME-Version | Shows the version of MIME (Multipurpose Internet Mail Extensions) used so you can ensure proper handling of attachments/HTML | MIME-Version: 1.0 |
Content-Type | Shows what the content type of the email is set to for accurate display and processing, e.g. text/HTML | Content-Type: multipart/alternative; |
Content-Transfer-Encoding | Shows how the message body is encoded for transport | Content-Transfer-Encoding: base64 |
Custom headers: Practical use cases
While most email headers can’t or shouldn’t be changed, there are a few custom headers that you can add or edit to optimize your workflows and improve the way recipients interact with your messages. You can also parse header information to use elsewhere, such as tracking data.
Below are some examples of custom headers and how you might use them.
Reply-To
Reply-To is a simple header, but it’s incredibly useful for managing email replies effectively. When it comes to transactional emails, your messages are likely being sent by an email address that doesn’t belong to an active or monitored inbox, like info@company.com.
But it’s also just as likely that your customers or users will occasionally have questions or concerns regarding the communication you send them. So using the Reply-To header is an easy way to direct their replies to someone who will read it and respond, like support@company.com.
In-Reply-To and Message-ID
This is an example of when you would need to parse the data from an email header and add it to a reply as the value for another header.
Using the In-Reply-To and Message-ID headers, you can organize conversations and create email threads in the inbox and ticketing systems. This makes it easier for support agents to track conversation history and work more efficiently, while improving the experience for recipients.
It involves extracting the Message-ID from the original inbound message and then inserting an In-Reply-To header with the original Message-ID as the value for all replies.
List-Unsubscribe
The List-Unsubscribe header tells email clients how recipients can unsubscribe from receiving future emails. It will typically include a mailto link, a URL or both, and will sometimes appear as an Unsubscribe button in the mailbox interface.
Most ESPs will take care of the List-Unsubscribe header for you, ensuring they are RFC 8058 compliant. But you can customize it if you want to control your unsubscribe flow or customize the way you track unsubscribes.
Custom X-Headers
X-Headers provide a flexible way for developers to pass any kind of data in an email, basically allowing you to create any header you like by simply prefixing the header with X-. They won’t affect the email’s journey, formatting or anything else.
Some interesting use cases for custom headers include:
Adding custom tracking IDs, for example, X-Tracking-ID: 09876abcdef
Prioritizing or routing emails, for example, adding X-Priority: High
Providing data for better personalization, monitoring and more, for example, X-Template-ID: 9348tGNX927rvSFKZZ826bkfj
Best practices when working with email headers
Since email headers can impact deliverability and are essential for secure email sending, there are some key best practices to keep in mind when you’re working with them:
1. Make sure your From and Return-Path domains are aligned to prevent DMARC failures. When the domains for these headers match, it ensures the sender is who they claim to be (and not a phishing or spoofing attempt). If they aren’t aligned, the message is at risk of being rejected or sent to the spam folder.
2. Set your Content-Type headers properly to avoid rendering issues. It will also ensure that any special characters and non-Latin-based languages are displayed correctly (using charset=UTF-8).
3. Always include a plain-text version of your email for clients that don’t support HTML. MailerSend does this for you automatically.
4. Avoid passing any sensitive data through custom headers. These are transmitted in plain text and are visible to the recipient.
5. Use email testing tools, header analyzers like MXToolbox, and logs to verify header rendering and authentication. You can check out headers in MailerSend’s logs.
6. Keep custom headers to a minimum so that they don’t impact your email’s overall size.
Don’t sleep on email headers
OK, we’ll admit, email headers aren’t the most exciting thing. But when you think outside the box, they can help you optimize your workflows and make your communications more user-friendly.
Plus, if you’re ever faced with deliverability issues, email headers are a great place to start to check if your email authentication and configuration is all in order.
