diff --git a/mailer.rst b/mailer.rst
index d407a0568c6..a3e3866aa72 100644
--- a/mailer.rst
+++ b/mailer.rst
@@ -730,6 +730,47 @@ adding a text header ``X-Transport`` to an email::
$email->getHeaders()->addTextHeader('X-Transport', 'important');
$mailer->send($email);
+Adding Tags and Metadata to Emails
+----------------------------------
+
+Certain 3rd party transports support email *tags* and *metadata*. These can be
+used by the 3rd party service for grouping, tracking and workflows. The
+:class:`Symfony\\Component\\Mailer\\Header\\TagHeader` and
+:class:`Symfony\\Component\\Mailer\\Header\\MetadataHeader` headers can be
+added to your email. If your transport supports these headers, they will be
+applied in the format specific to the transport.
+
+.. versionadded:: 5.1
+
+ The :class:`Symfony\\Component\\Mailer\\Header\\TagHeader` and
+ :class:`Symfony\\Component\\Mailer\\Header\\MetadataHeader` classes were
+ introduced in Symfony 5.1.
+
+The following 3rd party transports currently support tags and metadata:
+
+* Postmark
+* Mailgun
+* MailChimp
+
+For example, say you want to tag an email and add some metadata::
+
+ use Symfony\Component\Mailer\Header\MetadataHeader;
+ use Symfony\Component\Mailer\Header\TagHeader;
+
+ $email->getHeaders()->add(new TagHeader('password-reset'));
+ $email->getHeaders()->add(new MetadataHeader('Color', 'blue'));
+ $email->getHeaders()->add(new MetadataHeader('Client-ID', '12345'));
+
+When sending this email with a transport that supports tags and metadata, the transport
+will convert these to their appropriate format. If using a transport that does not
+support tags and metadata, they will be added as custom headers:
+
+.. code-block:: text
+
+ X-Tag: password-reset
+ X-Metadata-Color: blue
+ X-Metadata-Client-ID: 12345
+
Development & Debugging
-----------------------
pFad - Phonifier reborn
Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.
Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.
Alternative Proxies:
Alternative Proxy
pFad Proxy
pFad v3 Proxy
pFad v4 Proxy