Merge pull request #7329 from segmentio/develop

one-off

Author: forstisabella

src/connections/destinations/catalog/actions-hubspot-cloud/index.md

@@ -95,7 +95,10 @@ Search Fields to associate |  This finds a unique record of custom object based
 ObjectType to associate | To associate the newly created and updated custom object record with another object type, select the object type you want it to be associated with.
 Association Label | Select an association label between both the object types. From the HubSpot Dashboard, you can create associations between any type of object. To create an association label: <br>1. Log in to the [HubSpot Dashboard](https://app.hubspot.com/){:target="_blank"}. <br>2. Go to **Data Management > Objects > Custom Objects**. <br>3. Go to the **Associations** tab and click **Create association label**. 
 
-## FAQ and troubleshooting
+## FAQs and troubleshooting
+
+### Why am I receiving a `Contact already exists` error?
+This error only applies to integrations with 2 mappings that can create profiles in HubSpot. Initially, the Upsert Contact action seeks to update an existing contact. If no contact is found, a subsequent attempt is made to create a new contact, potentially leading to 3 separate HubSpot API requests. For example, an `Expired Authentication` error may occur if the token expires on the initial request, prompting a token refresh and a subsequent request. If the next error indicates `resource not found`, it means the contact wasn't located, leading to a second attempt to create the contact. However, this attempt might fail due to a `Conflict` error, suggesting the contact already exists. This situation can arise if you activate another mapping, which causes the contact to be created by the time the Upsert Contact Action attempts its final contact creation request, due to the Custom Behavioral Event Action being triggered as well.
 
 ### How do I send other standard objects to HubSpot?
 Segment provides prebuilt mappings for contacts and companies. If there are other standard objects you would like to create records in, please use the **Create Custom Object Record** action. For example, to create a deal in HubSpot, add a mapping for Create Custom Object Record, set up your Event Trigger criteria, and input a literal string of "deals" as the Object Type. You can use the Properties object to add fields that are in the [deals object](https://developers.hubspot.com/docs/api/crm/deals){:target="_blank"}, such as `dealname` and `dealstage`. The same can be done with other object types (for example, tickets, quotes, etc). Ending fields that are to go to HubSpot outside of the properties object isn't supported. This includes sending [associations](https://developers.hubspot.com/docs/api/crm/associations){:target="_blank"}.  Please note, Segment only supports creating new records in these cases; updates to existing records are only supported for contacts and companies. 

src/connections/destinations/catalog/actions-sendgrid-audiences/index.md

@@ -0,0 +1,85 @@
+---
+title: SendGrid Lists (Actions) Destination
+engage: true
+id: 67338e95bf70aed334093dae
+hidden: true
+---
+
+{% include content/plan-grid.md name="actions" %}
+
+[SendGrid Lists (Actions)](https://mc.sendgrid.com/contacts/?utm_source=segmentio&utm_medium=docs&utm_campaign=partners){:target="_blank”} helps customers organize their email recipients into targeted groups, enabling them to send personalized, relevant content to specific audiences. This improves engagement, increases email deliverability, and streamlines campaign management.
+
+This destination is maintained by Segment. For any issues with the destination, [contact the Segment Support team](mailto:[email protected]).
+
+## Getting started
+
+SendGrid Lists (Actions) is designed to work with Engage Audiences only. The steps below outline how to create and connect the Destination to Engage and then to an Engage Audience. SendGrid Lists (Actions) is not designed to connect to Connections Sources. 
+
+### Create a SendGrid API Key
+1. Sign in to your SendGrid account, then navigate to **Settings** > **API Keys**.
+2. Click **Create API Key** and follow the instructions to generate a new API key. Be sure to grant the API key **Full Access** permission. 
+3. Save the API key value in a secure location, as you will need it in later steps.
+
+### Connect a SendGrid Lists (Actions) destination to an Engage Space
+
+1. From your Segment workspace's home page, navigate to **Engage** > **Engage Settings** > **Settings** and click **Add destination**. 
+2. Search for SendGrid Lists (Actions) and select the SendGrid Lists (Action) tile. Click **Add Destination** and **Confirm Source**.
+3. On the Basic Settings screen, provide **Name** and **API Key** values in the specified fields, toggle "Enable destination" to on, and then click **Save Changes**. 
+
+### Create a Mapping
+
+1. From your Segment workspace's home page, click **Connections** > **Destinations** and select the SendGrid Lists (Actions) destination you previously created.
+2. Click on **Mappings** > **New Mapping** > **Sync Audience** > **Save**. 
+3. On the next screen, enable the Mapping using the **Status** toggle.
+
+### Connect an Audience
+
+1. From your Segment workspace's home page, navigate to **Engage** > **Audiences** and select the Audience you'd like to sync to SendGrid. 
+2. Click **Add Destination**, and select the SendGrid Lists (Actions) destination you previously created.
+3. Enter a **List Name**, select **Default Setup**, and click **Save**. When prompted, select **Add 1 Destination**. 
+
+The SendGrid Lists (Actions) destination will now start to sync your Engage Audience to a SendGrid List.
+
+{% include components/actions-fields.html %}
+
+
+## Troubleshooting
+
+### Does Segment create Lists in SendGrid?
+Segment automatically creates Lists in SendGrid. If you provide a value in the **Name** field, Segment names the List the value you provided. If you do not provide a name in the  **Name** field, Segment gives the List the Engage Audience's **Audience Key** value. 
+
+### Does Segment create new Contacts in SendGrid?
+Segment creates Contacts in SendGrid if a Contact doesn't already exist for the user.
+
+### Does Segment delete Contacts from SendGrid?
+Segment doesn't delete Contacts from SendGrid. If you remove a user from an Engage Audience, Segment does remove the Contact from the associated SendGrid List, but doesn't delete the Contact from SendGrid. 
+
+## Best practices
+
+### Sending additional user traits
+Segment supports sending Engage user profile traits to SendGrid Contact User Attributes. The following additional manual configuration steps are required: 
+
+1. Use [Trait Enrichment](/docs/engage/trait-activation/trait-enrichment/) to include specific user profile traits when syncing users to a SendGrid List. 
+2. Standard User Attributes: Use the [Sync Audience Action](#sync-audience-action)'s User Attributes field to map the following [Contact Profile Fields](https://www.twilio.com/docs/sendgrid/ui/managing-contacts/segmenting-your-contacts#contact-profile-fields){:target="_blank”} to SendGrid:
+ - First Name
+ - Last Name
+ - Phone Number (must be in [E.164](https://www.twilio.com/docs/glossary/what-e164){:target="_blank”} format)
+ - Address Line 1
+ - Address Line 2
+ - City
+ - State/Province/Region
+ - Country
+ - Postal Code
+3. Custom User Attributes: Define a custom User Attribute in SendGrid, then use [Sync Audience ](#sync-audience-action) Action to send custom User Attributes to SendGrid using the Custom Fields field. You can only send string, number, and date values to SendGrid with this method.
+
+### Supported identifiers 
+At least one of the following identifier types is required when syncing members of an Engage Audience to a SendGrid List:
+ - Email Address (must be a valid email address)
+ - Anonymous ID
+ - Phone Number ID (must be in [E.164](https://www.twilio.com/docs/glossary/what-e164){:target="_blank”} format)
+ - External ID 
+ 
+To sync Engage users to a list using Anonymous ID, Phone Number ID, and External ID identifier types, complete the following configuration steps: 
+
+1. Configure [ID Sync](/docs/engage/trait-activation/id-sync/) to include Anonymous ID, Phone Number ID, or External ID identifiers when syncing users from an Engage Audience to the SendGrid List. 
+2. Map the Anonymous ID, Phone Number ID, and External ID identifiers using the [Sync Audience ](#sync-audience-action) Action's Anonymous ID, Phone Number ID, and External ID fields. 

src/connections/sources/catalog/libraries/website/javascript/faq.md

@@ -141,4 +141,5 @@ If you need this functionality, you have a couple of options:
 **Use downstream tools**: Many analytics platforms, like Google Analytics, can automatically handle IP-to-geolocation conversion.
 **Use a third-party API**: Alternatively, you can use third-party services like Geolocation API to convert IP addresses to geolocation data. Afterward, you can pass this information as a trait in Identify calls or as a property in Track calls to Segment. This allows you to manage geolocation data according to your specific needs, though it will likely require engineering resources.
 
-
+## Why is my payload populating incorrectly?
+Payload parameters aren't populated in a guaranteed order. Your payload should still be ingested as long as all necessary parameters are included.