From d43579833c2aca3cb35989914c2526bf28fbe4fe Mon Sep 17 00:00:00 2001
From: Javier Eguiluz <javier.eguiluz@gmail.com>
Date: Fri, 29 May 2020 17:45:11 +0200
Subject: [PATCH] [Mailer] Documented the tag and metadata headers

---
 mailer.rst | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/mailer.rst b/mailer.rst
index 88241881469..db48c16d386 100644
--- a/mailer.rst
+++ b/mailer.rst
@@ -183,6 +183,39 @@ Alternatively, you can pass multiple addresses to each method::
         // ...
     ;
 
+Message Headers
+~~~~~~~~~~~~~~~
+
+Messages include a number of header fields to describe their contents. Symfony
+sets all the required headers automatically, but you can set your own headers
+too. There are different types of headers (Id header, Mailbox header, Date
+header, etc.) but most of the times you'll set text headers::
+
+    $email = (new Email())
+        ->getHeaders()
+            // this header tells auto-repliers ("email holiday mode") to not
+            // reply to this message because it's an automated email
+            ->addTextHeader('X-Auto-Response-Suppress', 'OOF, DR, RN, NRN, AutoReply');
+
+        // ...
+    ;
+
+When using a mailer service that supports tags and metadata, consider using the
+``TagHeader`` and ``MetadataHeader`` headers instead of the plain text headers::
+
+    use Symfony\Component\Mailer\Header\MetadataHeader;
+    use Symfony\Component\Mailer\Header\TagHeader;
+
+    $email->getHeaders()->add(new TagHeader('password-reset'));
+    $email->getHeaders()->add(new MetadataHeader('Client-ID', '12345'));
+
+If your mailer doesn't support these tag/metadata headers, they are added to the
+message as text headers (``X-Tag: password-reset``, ``X-Metadata-Client-ID: 12345``).
+
+.. versionadded:: 5.1
+
+    The ``TagHeader`` and ``MetadataHeader`` headers were introduced in Symfony 5.1.
+
 Message Contents
 ~~~~~~~~~~~~~~~~