Merge pull request #5475 from segmentio/subscription-groups-updates

Update Subscription Groups Content

Author: pwseg

src/engage/campaigns/broadcasts.md

@@ -24,8 +24,7 @@ Follow these steps to create an email broadcast:
     - To send a message to a pre-built audience, choose `Part of an Audience`, then select the audience.
     - To exclude users from the audience, click **Add condition** in the **And who** section. Click **And who**, then select **And not who**. Segment will exclude users from the audience you choose.
 5. Click **Preview** to estimate the audience size.
-6. Select the subscription group that you want to receive your broadcast.
-    - Segment recommends only sending broadcasts to users with a `subscribed` status. 
+6. Select the [subscription group](/docs/engage/user-subscriptions/subscription-groups/) that you want to receive your broadcast.
 7. Select **Build**, then choose either **Build a new email** or select a template.
 8. Fill out the **Email settings** fields, choose your email editor, then click **Continue**.
 9. Configure your email, then click **Continue**.

src/engage/campaigns/email-campaigns.md

@@ -43,7 +43,7 @@ Follow these steps to create an email campaign:
 2. From the **Select a Step** window, click **Send an email**.
 3. In the **Send Email** window, select **Build a new email** or [Use a template](/docs/engage/content/email/template/) to choose an existing email template.
 4. Build or edit your design, then click **Save Email**.
-5. Fill out all **Send Email** fields relevant to your campaign, then click **Save**.
+5. Fill out all **Send Email** fields relevant to your campaign, select the [subscription states or groups](/docs/engage/user-subscriptions/subscription-groups/) that you want to receive your email, then click **Save**.
 
 Some email campaign fields, like **Sender email** and **Subject**, are required.  The Send Email window indicates required fields with an asterisk.  Refer to the [email campaign fields](/docs/engage/campaigns/email-campaigns/#email-campaign-fields) table for a full description of available email fields.
 

src/engage/content/email/editor.md

@@ -118,6 +118,10 @@ Add an unsubscribe link to text:
 
 You can alternatively add a [predefined unsubscribe](#add-blank-columns-or-predefined-content-blocks) link content block.
 
+## Add a manage preference link
+
+Engage also adds a manage preference link to templates. The manage preference link lets your customers opt in and out of email groups on an individual basis instead of unsubscribing from all your campaigns. For more information, see [subscription groups](/docs/engage/user-subscriptions/subscription-groups/).
+
 ## Personalize with merge tags
 Add merge tags in the Drag and Drop Editor to personalize your message with user profile traits.
 

src/engage/content/email/template.md

@@ -58,13 +58,23 @@ You can also add merge tags in the heading or body text as you design an email w
 > info ""
 > To learn more about profile traits, visit Segment's [Computed Traits](/docs/engage/audiences/computed-traits) and [SQL Traits](/docs/engage/audiences/sql-traits/) documentation.
 
-## Include unsubscribe links
+## Include unsubscribe and manage preference links
+
+When you build an email template, you'll need to include links that your customers can access to unsubscribe and manage their email preferences. You'll find both in the **Special Links** dropdown menu of the **Insert/Edit link** window.
+
+### Unsubscribe links
 
 When you build email templates, it's your responsibility to include an unsubscribe link in your message. Add unsubscribe links to an email template from the Drag and Drop or HTML editors.
 
 When a recipient clicks on an unsubscribe link, they'll see a confirmation page and the recipient's subscription state is updated.
 
-Only send messages to subscribed users. Learn more about [User Subscriptions](/docs/engage/user-subscriptions/) in Twilio Engage.
+Learn more about [User Subscriptions](/docs/engage/user-subscriptions/) in Twilio Engage.
+
+### Manage preference links
+
+The manage preference link lets your customers opt in and out of email groups on an individual basis instead of unsubscribing from all your campaigns.
+
+For more information, see [subscription groups](/docs/engage/user-subscriptions/subscription-groups/).
 
 ## Clone an Email template
 

src/engage/profiles/csv-upload.md

@@ -129,4 +129,4 @@ Please note the following limits as you upload CSV files to Twilio Engage:
 
 ## Message consent
 
-Only send messages to subscribed users. If a recipient deletes or flags an unwanted message as spam, inbox providers might start to filter your messages straight to spam folders. View more SendGrid delivery [Best Practices](https://sendgrid.com/blog/why-are-my-emails-going-to-spam/){:target="_blank"} to prevent email from going to spam.
+Segment recommends sending to subscribed users. If a recipient deletes or flags an unwanted message as spam, inbox providers might start to filter your messages straight to spam folders. View more SendGrid delivery [Best Practices](https://sendgrid.com/blog/why-are-my-emails-going-to-spam/){:target="_blank"} to prevent email from going to spam.

src/engage/user-subscriptions/subscription-groups.md

@@ -54,6 +54,60 @@ Once you've created a subscription group and added subscribers to it, follow the
 1. [Build a new email template](/docs/engage/content/email/template/#build-an-email-template). The template should include both unsubscribe and manage preferences links. For more on special links, view [Add unsubscribe links](/docs/engage/content/email/editor/#add-unsubscribe-links).
 2. During email setup, select the subscription group you want to send to from the **Which subscription states should receive this message?** dropdown, then finish [setting up and publishing your campaign](/docs/engage/campaigns/email-campaigns/#create-test-and-publish-your-email-campaign).
 
+## Set subscription group status with the Identify call
+
+Segment supports subscription groups for email. You can send statuses for email subscription groups using the [Identify call](/docs/connections/spec/identify/). 
+
+To set susbcription groups with the Identify call, you'll need to include a key-value pair of `"type": "EMAIL"` and the `groups` object, like in the following sample payload:
+
+```json
+{
+  "userId": "12aBCDeFg4hIjKlM5OPq67RS8Tu",
+  "context": {
+    "messaging_subscriptions": [
+      {
+        "key": "(123) 555-5555",
+        "type": "SMS",
+        "status": "SUBSCRIBED" | "UNSUBSCRIBED" | "DID_NOT_SUBSCRIBE"
+      },
+      {
+        "key": "(123) 555-5555",
+        "type": "WhatsApp",
+        "status": "SUBSCRIBED" | "UNSUBSCRIBED" | "DID_NOT_SUBSCRIBE"
+      },
+      {
+        "key": "[email protected]",
+        "type": "EMAIL",
+        "status": "SUBSCRIBED" | "UNSUBSCRIBED" | "DID_NOT_SUBSCRIBE",
+        "groups": [
+            {
+               "name": "newsletter",
+               "status": "SUBSCRIBED" | "UNSUBSCRIBED" | "DID_NOT_SUBSCRIBE"
+            },
+            {
+               "name": "marketing updates",
+               "status": "SUBSCRIBED" | "UNSUBSCRIBED" | "DID_NOT_SUBSCRIBE"
+            }
+        ]
+      }
+    ],
+    "externalIds": [
+      {
+        "id": "(123) 555-5555",
+        "type": "phone",
+        "collection": "users",
+        "encoding": "none"
+      }
+    ],
+    "traits": {
+       "email": "[email protected]"
+    }
+  },
+  "integrations": {},
+  "traits": {}
+}
+```
+
 ## Frequently asked questions
 
 {% faq %}

src/engage/user-subscriptions/subscription-states.md

@@ -22,9 +22,6 @@ The following table displays the four subscription states:
 | `did-not-subscribe`      | A user gave you their contact information but made no decision about receiving marketing campaigns.         | A user provided their email address or phone number in an online transaction, but didn't sign up to receive your weekly newsletter. |
 | No subscription status | A user did not give you their contact information and made no decision about receiving marketing campaigns. | Segment collected an email or phone number through identity resolution. No user actively provided the email or phone number.               |
 
-> warning "Sending Permissions"
-> You can only send Engage campaigns to contacts with a subscribed user state.
-
 ## Understanding subscription states
 
 You can gain insight into your audience profiles by learning how and why each subscription state is associated with a user’s profile.  Below, you’ll find the four states described in detail, along with common scenarios that produce those states.
@@ -39,8 +36,6 @@ Subscribed users have intentionally requested to receive your marketing material
 - A user who signed up for your marketing campaigns on your website’s signup form
 - A user who signed up for marketing campaigns at an in-person event, like a conference
 
-**You may only send Engage campaigns to subscribed users. User subscriptions help you understand a user's preference to receive or not receive your marketing content.**
-
 It's your responsibility to ensure that Segment correctly reflects your users' subscription choices. Failure to do so may put you in violation of legislation like [CAN-SPAM](https://www.ftc.gov/business-guidance/resources/can-spam-act-compliance-guide-business){:target="_blank"}, [TCPA](https://www.twilio.com/docs/glossary/what-is-telephone-consumer-protection-act-tcpa){:target="_blank"}, or [GDPR](https://gdpr-info.eu/){:target="_blank"}.
 
 ### Unsubscribed