Document new incoming email address format

1 files changed, 38 insertions, 32 deletions

diff --git a/doc/administration/incoming_email.md b/doc/administration/incoming_email.md
index 27a3710632d..05873e01a08 100644
--- a/doc/administration/incoming_email.md
+++ b/doc/administration/incoming_email.md
@@ -13,43 +13,45 @@ GitLab has several features based on receiving incoming emails:
 
 ## Requirements
 
-Handling incoming emails requires an [IMAP]-enabled email account. GitLab
-requires one of the following three strategies:
+Handling incoming emails requires an [IMAP](https://en.wikipedia.org/wiki/Internet_Message_Access_Protocol)-enabled
+email account. GitLab requires one of the following three strategies:
 
-- Email sub-addressing
-- Dedicated email address
+- Email sub-addressing (recommended)
 - Catch-all mailbox
+- Dedicated email address (supports Reply by Email only)
 
 Let's walk through each of these options.
 
-**If your provider or server supports email sub-addressing, we recommend using it.
-Most features (other than reply by email) only work with sub-addressing.**
-
-[IMAP]: https://en.wikipedia.org/wiki/Internet_Message_Access_Protocol
-
 ### Email sub-addressing
 
 [Sub-addressing](https://en.wikipedia.org/wiki/Email_address#Sub-addressing) is
-a feature where any email to `user+some_arbitrary_tag@example.com` will end up
-in the mailbox for `user@example.com`, and is supported by providers such as
-Gmail, Google Apps, Yahoo! Mail, Outlook.com and iCloud, as well as the
-[Postfix mail server] which you can run on-premises.
-
-[Postfix mail server]: reply_by_email_postfix_setup.md
+a mail server feature where any email to `user+arbitrary_tag@example.com` will end up
+in the mailbox for `user@example.com` . It is supported by providers such as
+Gmail, Google Apps, Yahoo! Mail, Outlook.com, and iCloud, as well as the
+[Postfix mail server](reply_by_email_postfix_setup.md), which you can run on-premises.
+
+TIP: **Tip:**
+If your provider or server supports email sub-addressing, we recommend using it.
+A dedicated email address only supports Reply by Email functionality.
+A catch-all mailbox supports the same features as sub-addressing as of GitLab 11.7,
+but sub-addressing is still preferred because only one email address is used,
+leaving a catch-all available for other purposes beyond GitLab.
 
-### Dedicated email address
+### Catch-all mailbox
 
-This solution is really simple to set up: you just have to create an email
-address dedicated to receive your users' replies to GitLab notifications.
+A [catch-all mailbox](https://en.wikipedia.org/wiki/Catch-all) for a domain
+receives all emails addressed to the domain that do not match any addresses that
+exist on the mail server.
 
-### Catch-all mailbox
+As of GitLab 11.7, catch-all mailboxes support the same features as
+email sub-addressing, but email sub-addressing remains our recommendation so that you
+can reserve your catch-all mailbox for other purposes.
 
-A [catch-all mailbox](https://en.wikipedia.org/wiki/Catch-all) for a domain will
-"catch all" the emails addressed to the domain that do not exist in the mail
-server.
+### Dedicated email address
 
-GitLab can be set up to allow users to comment on issues and merge requests by
-replying to notification emails.
+This solution is relatively simple to set up: you just need to create an email
+address dedicated to receive your users' replies to GitLab notifications. However,
+this method only supports replies, and not the other features of [incoming email](#incoming-email).
 
 ## Set it up
 
@@ -160,14 +162,16 @@ for a real-world example of this exploit.
     gitlab_rails['incoming_email_idle_timeout'] = 60
     ```
 
-    Configuration for Microsoft Exchange mail server w/ IMAP enabled, assumes
-    mailbox incoming@exchange.example.com
+    Configuration for Microsoft Exchange mail server w/ IMAP enabled, assumes the
+    catch-all mailbox incoming@exchange.example.com
 
     ```ruby
     gitlab_rails['incoming_email_enabled'] = true
 
-    # The email address replies are sent to - Exchange does not support sub-addressing so %{key} is not used here
-    gitlab_rails['incoming_email_address'] = "incoming@exchange.example.com"
+    # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to.
+    # The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`).
+    # Exchange does not support sub-addressing, so a catch-all mailbox must be used.
+    gitlab_rails['incoming_email_address'] = "incoming-%{key}@exchange.example.com"
 
     # Email account username
     # Typically this is the userPrincipalName (UPN)
@@ -279,15 +283,17 @@ for a real-world example of this exploit.
       idle_timeout: 60
     ```
 
-    Configuration for Microsoft Exchange mail server w/ IMAP enabled, assumes
-    mailbox incoming@exchange.example.com
+    Configuration for Microsoft Exchange mail server w/ IMAP enabled, assumes the
+    catch-all mailbox incoming@exchange.example.com
 
     ```yaml
     incoming_email:
       enabled: true
 
-      # The email address replies are sent to - Exchange does not support sub-addressing so %{key} is not used here
-      address: "incoming@exchange.example.com"
+      # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to.
+      # The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`).
+      # Exchange does not support sub-addressing, so a catch-all mailbox must be used.
+      address: "incoming-%{key}@exchange.example.com"
 
       # Email account username
       # Typically this is the userPrincipalName (UPN)