Email special headers

Email headers carry more than the sender address and the subject line. A few special email headers tell Gmail and Outlook how to show an unsubscribe button and how to group messages that come from the same sender.

List-Unsubscribe puts the opt-out in the client UI

Modern email services like Gmail and Outlook use List-Unsubscribe headers to let users opt out with a single click. Instead of digging through the email for a tiny “unsubscribe” link, you get a clear button at the top. This improves deliverability for senders and makes it easier for users to manage subscriptions.

Bulk senders need one more piece. Gmail and Yahoo expect one-click unsubscribe as defined in RFC 8058: a List-Unsubscribe-Post: List-Unsubscribe=One-Click header, plus an HTTPS endpoint that accepts a POST request.

List-ID and Precedence tell the provider this is bulk mail

To prevent inbox clutter, email providers use headers like List-ID and Precedence to group related emails together. For example:

• List-ID: Helps categorize newsletters from the same source.

• Precedence: Bulk: Tells the email provider it’s part of a mass mailing, which can influence filtering.

Point List-Unsubscribe at a mailto address

Both examples below send with Nodemailer. The first one gives the List-Unsubscribe header a mailto address and an HTTPS URL, so the client can take either route.

const info = await transporter.sendMail({
	from: '"My Newsletter" <newsletter[at]yourdomain.com>',
	to: "subscriber[at]example.com",
	subject: "Your Weekly Update",
	text: "Here is your update!",
	html: "<p>Here is your update!</p>",
 
	// Special headers
	headers: {
		"List-Unsubscribe":
			"<mailto:unsubscribe[at]yourdomain.com>, <https://yourdomain.com/unsubscribe>",
		"List-ID": "weekly-updates.yourdomain.com",
		Precedence: "bulk",
	},
});

When a recipient clicks the unsubscribe link, an unsubscribe request will be emailed to the email address you've provided.

Point List-Unsubscribe at a URL instead

Drop the mailto value when every opt-out should land in your own web flow.

const info = await transporter.sendMail({
	from: '"My Newsletter" <newsletter[at]yourdomain.com>',
	to: "subscriber[at]example.com",
	subject: "Your Weekly Update",
	text: "Here is your update!",
	html: "<p>Here is your update!</p>",
 
	// Special headers
	headers: {
		"List-Unsubscribe": "<https://yourdomain.com/unsubscribe>",
		"List-ID": "weekly-updates.yourdomain.com",
		Precedence: "bulk",
	},
});

When a recipient clicks the unsubscribe link, the user will be redirected to the provided URL where the rest of the flow will continue.

By using these headers correctly, email senders improve engagement, while users get a cleaner, more manageable inbox.