From be8cf064e5bd1732a32288079719793a0cefa59c Mon Sep 17 00:00:00 2001
From: Kevin Bond <kevinbond@gmail.com>
Date: Wed, 9 Mar 2022 09:53:12 -0500
Subject: [PATCH 1/2] add mail/notification tags & metadata docs

---
 mail.md          | 18 ++++++++++++++++++
 notifications.md | 20 ++++++++++++++++++++
 2 files changed, 38 insertions(+)

diff --git a/mail.md b/mail.md
index 9ced46384c8..91513cd1259 100644
--- a/mail.md
+++ b/mail.md
@@ -11,6 +11,7 @@
     - [View Data](#view-data)
     - [Attachments](#attachments)
     - [Inline Attachments](#inline-attachments)
+    - [Adding Tags & Metadata](#adding-tags-metadata)
     - [Customizing The Symfony Message](#customizing-the-symfony-message)
 - [Markdown Mailables](#markdown-mailables)
     - [Generating Markdown Mailables](#generating-markdown-mailables)
@@ -470,6 +471,23 @@ If you already have a raw image data string you wish to embed into an email temp
 </body>
 ```
 
+<a name="adding-tags-metadata"></a>
+### Adding Tags & Metadata
+
+Tags and metadata can be added to your `Mailable` - these are used by your email service for filtering/processing:
+
+    /**
+     * Build the message.
+     *
+     * @return $this
+     */
+    public function build()
+    {
+        return $this->view('emails.orders.shipped')
+                    ->tag('shipment')
+                    ->metadata('order_id', $this->order->id);
+    }
+
 <a name="customizing-the-symfony-message"></a>
 ### Customizing The Symfony Message
 
diff --git a/notifications.md b/notifications.md
index e2ea7962859..51f2e33b490 100644
--- a/notifications.md
+++ b/notifications.md
@@ -16,6 +16,7 @@
     - [Customizing The Mailer](#customizing-the-mailer)
     - [Customizing The Templates](#customizing-the-templates)
     - [Attachments](#mail-attachments)
+    - [Adding Tags & Metadata](#adding-tags-metadata)
     - [Using Mailables](#using-mailables)
     - [Previewing Mail Notifications](#previewing-mail-notifications)
 - [Markdown Mail Notifications](#markdown-mail-notifications)
@@ -526,6 +527,25 @@ The `attachData` method may be used to attach a raw string of bytes as an attach
                     ]);
     }
 
+<a name="adding-tags-metadata"></a>
+### Adding Tags & Metadata
+
+Tags and metadata can be added to the `MailMessage` - these are used by your email service for filtering/processing:
+
+    /**
+     * Get the mail representation of the notification.
+     *
+     * @param  mixed  $notifiable
+     * @return \Illuminate\Notifications\Messages\MailMessage
+     */
+    public function toMail($notifiable)
+    {
+        return (new MailMessage)
+                    ->greeting('Comment Upvoted!')
+                    ->tag('upvote')
+                    ->metadata('comment_id', $this->comment->id);
+    }
+
 <a name="using-mailables"></a>
 ### Using Mailables
 

From c11b18c09476a588d0089cdb777ef53ce8f8546c Mon Sep 17 00:00:00 2001
From: Taylor Otwell <taylor@laravel.com>
Date: Thu, 10 Mar 2022 12:13:26 -0600
Subject: [PATCH 2/2] formatting

---
 mail.md | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/mail.md b/mail.md
index 91513cd1259..be9c61ef492 100644
--- a/mail.md
+++ b/mail.md
@@ -11,7 +11,7 @@
     - [View Data](#view-data)
     - [Attachments](#attachments)
     - [Inline Attachments](#inline-attachments)
-    - [Adding Tags & Metadata](#adding-tags-metadata)
+    - [Tags & Metadata](#tags-and-metadata)
     - [Customizing The Symfony Message](#customizing-the-symfony-message)
 - [Markdown Mailables](#markdown-mailables)
     - [Generating Markdown Mailables](#generating-markdown-mailables)
@@ -471,10 +471,10 @@ If you already have a raw image data string you wish to embed into an email temp
 </body>
 ```
 
-<a name="adding-tags-metadata"></a>
-### Adding Tags & Metadata
+<a name="tags-and-metadata"></a>
+### Tags & Metadata
 
-Tags and metadata can be added to your `Mailable` - these are used by your email service for filtering/processing:
+Some third-party email providers such as Mailgun and Postmark support message "tags" and "metadata", which may be used to group and track emails sent by your application. You may add tags and metadata to an email message via the `tag` and `metadata` methods:
 
     /**
      * Build the message.
@@ -488,6 +488,10 @@ Tags and metadata can be added to your `Mailable` - these are used by your email
                     ->metadata('order_id', $this->order->id);
     }
 
+If your application is using the Mailgun driver, you may consult Mailgun's documentation for more information on [tags](https://documentation.mailgun.com/en/latest/user_manual.html#tagging-1) and [metadata](https://documentation.mailgun.com/en/latest/user_manual.html#attaching-data-to-messages). Likewise, the Postmark documentation may also be consulted for more information on their support for [tags](https://postmarkapp.com/blog/tags-support-for-smtp) and [metadata](https://postmarkapp.com/support/article/1125-custom-metadata-faq).
+
+If your application is using Amazon SES to send emails, you should use the `metadata` method to attach [SES "tags"](https://docs.aws.amazon.com/ses/latest/APIReference/API_MessageTag.html) to the message.
+
 <a name="customizing-the-symfony-message"></a>
 ### Customizing The Symfony Message