[Mailer] Documented the tag and metadata headers

javiereguiluz · javiereguiluz · commit e97b18668459 · 2020-05-29T17:45:11.000+02:00
diff --git a/mailer.rst b/mailer.rst
@@ -201,6 +201,22 @@ header, etc.) but most of the times you'll set text headers::
         // ...
     ;
 
+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
 ~~~~~~~~~~~~~~~~
 
