Email Marketing & Communications
This guide details the most popular use cases for integrating reviews, visual user-generated content (UGC), loyalty and referrals, and SMS with your marketing communications platform.
Main use cases covered in this toolkit:
- Display a product’s star rating and the average score
- Display top product reviews and AI sentences
- Segment customers based on recent reviews & aggregated data
- Trigger follow-up messages and flows based on review
- Display visual UGC on a product
- Display visual UGC from any custom album
- Sync historical customer data for segmentation and personalization
- Trigger emails and update customer profiles based on loyalty events and milestones
- Sync SMS subscribers & lists to Yotpo
- Sync email subscribers & lists from Yotpo
- Trigger a Yotpo SMS & Email flow with an event from your platform
Please note:
Each of the listed use cases requires that the customer has the applicable Yotpo Product (Reviews, Visual UGC, and Loyalty) available to them and installed.
Have you registered your app yet?
Before you start building your app on top of Yotpo’s App Market API, you first need to register it with us. If you haven’t done so yet, refer to the steps in our Welcome guide.
Yotpo Reviews
Sync product data, including review quantity, average score, and top reviews and images between Yotpo and your platform in order to increase click-through rates on products, abandoned cart messages, and more.
Display a product’s star rating and average score
Retrieve product data using the product or all products endpoints, either to display it in real-time or to store it in your system. We recommend refreshing the data every day or every few hours.
These endpoints allow you to retrieve published data on products in the Yotpo system, including their average review score (average_score) and the total number of reviews written about them (total_reviews).
Get top product reviews and AI sentences
Use the best reviews or best sentences endpoint to retrieve your top product reviews. These endpoints will return only published reviews with a positive overall sentiment score, using Yotpo’s powerful AI engine.
Make sure you provide the external_product_id parameter to pull relevant reviews about the actual product and not store or site reviews.
Since these endpoints utilize an AI (NLP) engine that works on English reviews only, you can use the top reviews endpoint as an alternative endpoint for non-English language stores and as a fall-back when a product does not have enough reviews with a positive sentiment score.
In the case that both endpoints do not retrieve any reviews (the product does not have positive enough reviews) we recommend pulling reviews for the product yotpo_site_reviews as a fallback (will return reviews collected about the brand/business).
Segment customers based on recent reviews & custom questions
To return the latest customer reviews, including answers to custom questions, and enhance your segmentation capabilities, simply retrieve all reviews and query by the customer’s email address or last sync date. This will return all reviews that have been updated in Yotpo, whether created or published/unpublished, since that date.
Segment customers based on aggregated data
Yotpo’s customer endpoints allow partners to pull a consumer’s record from Yotpo’s centralized CDP. This data can be pulled by customer email address or in bulk for all records updated since a set date.
Please note:
- Although some loyalty data is also available in this call, we recommend using the reviews information only (see below for Loyalty integration best practices).
- Yotpo’s CDP will only return verified reviews . Anonymous reviews, submitted on-site and not yet verified by the reviewer will not be returned even if published. If you are testing your app using a test account, make sure to verify your email when creating reviews to successfully retrieve this data.
Trigger follow-up messages and flows based on review
Use the review_create webhook event to set up follow-up messages for new reviews that were just received from a customer. You can use the review score to create different follow-up flows for positive reviews vs. negative reviews.
Please note:
- You may use the
include_nestedparameter to include user data, for example, the user that wrote the review.- According to Google’s reviews policies, site reviews cannot be incentivized in any way, while product reviews can. If you offer incentives through your platform, make sure to allow merchants to differentiate between site and product reviews using the
review_type_idfield in the response. When =1, the review is a product review and can be incentivized. When =2, the review was collected as a site review and must not be rewarded in any way.- Some merchants may also want to differentiate between verified buyer reviews, which are submitted automatically post-purchase and are therefore more authentic and valuable from a brand perspective, and anonymous reviews.
Announce to a customer that a review was published on the website
Use the review_updated webhook event to notify a consumer that their review was published on the website and bring them back to your website.
Please note:
- The webhook only means the review was published if ‘deleted’ = ‘false’ for the first time. The webhook may trigger when later moderation changes are made to the review, which the brand might not want to trigger an event for.
- Some merchants might also be interested in collecting reviews through your platform. To ensure the authenticity of the content collected, we do not currently offer this use case.
Yotpo Visual UGC
Display visual UGC on a product
Display photos or videos that were handpicked and published by the brand on abandoned carts and promotional communications by pulling them from the product images endpoint in real-time or storing them while updating at least daily.
Display visual UGC from an album
Display a gallery of photos or videos that the brand curated as a custom album. Just get the album ID from the photos or videos and then use the photos by album endpoint.
Yotpo Loyalty & Referrals
Sync historical customer data for segmentation and personalization
The historical customer sync is essential for segmentation and personalization of general marketing emails when a merchant already has loyalty members in Yotpo. In addition, there are times when a merchant might pause their Loyalty program or integration and need to re-sync all customers since a certain date. For both of these scenarios, you can use the ‘retrieve customers by date’ endpoint. This endpoint returns the most used loyalty properties only - if you’d like to retrieve all loyalty properties on a profile, you will need to run a subsequent call for each profile that has loyalty data, using the ‘fetch customer’ endpoint.
Another option (although far less optimal) is asking merchants to export customers from Yotpo manually (as CSV) and importing them into your system, the steps to do this in Yotpo can be found in this article.
Please note:
If the loyalty program is running while you run your historical customer sync, make sure that you are also listening to the points changed and tier status changed events and updating profiles, to avoid missing any changes.
Trigger emails and update customer profiles based on loyalty events and milestones
To start, the brand must implement your webhook URL in their Yotpo Loyalty admin settings. The merchant can also add an authentication header within Yotpo that will help you securely identify the merchant and origin of the webhook events. We recommend allowing the merchant to provide both systems with the specific authentication header they would like to use as Yotpo supports multiple webhook URLs (comma separated) but only one authentication header. This will avoid forcing the merchant to work insecurely or sharing your private key on another platform.
Once the webhook URL is placed in the admin, we recommend listening to and exposing to the merchant all webhook events listed here. The points changed event is specifically relevant for updating the customer record in your platform and keeping both systems in sync in real-time. Note that some of the other event payloads may include the same information that is being updated, but may also include specific fields that are relevant to that event and should be available for the merchant in the email content. Make sure to document these fields and how to use them in your platform.
Important!
- Multiple webhook URLs should be separated by a semicolon comma
- Webhook authentication can be populated with one string value only
Other important considerations
- For Email Marketing integrations, we strongly recommend exposing all webhook events listed here, as flow triggers in your system.
- The points changed & VIP tier changed events are specifically relevant for updating the customer profile in your platform and keeping profiles in both systems in sync in real-time. This is required to allow merchants to use loyalty data accurately for segmentation and personalization of messages in your system.
- Note that multiple events may fire at the same time, so merchants will need a way to determine priorities between events in flows.
- Note that sometimes events may fire more than once, due to retries when a response was delayed on your end. In that case, it’s important to filter out the recurring event fired.
- Most events will include the primary loyalty information on a customer, but may also include specific properties that are relevant to that specific event only (for example a personalized referral link or coupon code) that should be made available to be used in the specific flow as content and conditions (make sure to document these fields and how to use them in emails for your merchants).
- The ideal situation is to let the merchant determine whether to send each loyalty event triggered email as marketing or transactional, as this could vary by country / industry & legal advisor. If you need to pre-define which of the events will be sent as marketing vs. transactional messages, this link provides our recommendation (but please note that this is not a legally binding recommendation and you should rely on your own legal / privacy experts to make a final decision).
- The Referral Link Share event and Referral Share Reminder event includes both the information of the referrer and the referred friend. These events are primarily used to send an email to the referred friend with the link/code that gives them the discount. That being said, because the referred friend typically never opted-in to marketing emails, it is important to send this email as a one time email and not to opt-in the referred friend into other marketing emails, as they have not taken an action themselves to do so.
Please note:
We strongly recommend creating email & flow templates for each of the Yotpo events so that your merchants can easily add to their accounts and save them valuable time. Recommended email copies / flows can be found here.
Yotpo SMS & Email
SMS use cases
Capture and pass SMS subscribers to Yotpo SMS & Email
- Via API
- You can check first if the user is already subscribed to SMS (this is recommended), using this endpoint. The response Attribute that indicates if the user is opt-in to sms is:
"accepts_sms_marketing": true/false (boolean). - Use the create subscriber API endpoint to create a new subscriber.
- Replace ‘store_id’ with the app key received in the app install by the merchant
- Replace ‘token’ with the access token you created with your app credentials and the temporary code received as a result of the installation by the merchant.
- The list Id can be found by clicking on “view” next to the list’s name in Yotpo SMS & Email. The List ID is displayed at the end of the page URL.
- You can check first if the user is already subscribed to SMS (this is recommended), using this endpoint. The response Attribute that indicates if the user is opt-in to sms is:
Important!
- The opt-in source In Yotpo SMS & Email will show as “API”.
- A welcome flow can be initiated by a user joining the specific list you defined in the API call. Set List as a condition to trigger the welcome flow, and choose the list you created.
- Additional custom properties on a customer will be accepted in the near future (coming in Q2-Q3)
- To pass Yotpo the first & last name and other customer info: First of all, check if the customer already has these details available in Yotpo using the Retrieve customer endpoint. Only for missing information, use the Create/update customer endpoint (adding fields that already exist in Yotpo will overwrite the existing values, pulled from eCommerce integrations).
- First, you need to create a customer, wait 60 seconds and then create a subscriber to initiate a welcome flow with a first name (using a short code).
- If you are the main email marketing provider for the brand and accept email marketing is set to false, you may update this field as well (allow merchants to segment these customers when building flows in Yotpo SMS & Email).
- Via Shopify
- You can capture SMS subscribers with Shopify's checkout. See here how to set it up.
- Set a welcome flow within Yotpo SMS & Email. Set the trigger to “New Subscriber Confirmation” and add a condition “Available subscription sources equals Checkout”.
- Modify the messaging to suit the overall tone of the brand.
Capture email in Yotpo SMS & Email and share it with your platform
Email can be captured currently by using the Yotpo embedded form, learn how to create one here. When captured in a Yotpo SMS & Email form we will update Shopify with the status “Email subscribed” under marketing status. The following tags will be added to the customer profile: “SMSBump”, “SMSBump_subscribed”.
Share with Yotpo SMS & Email lists and segments created in your platform
We do not have an API for receiving lists/segments (with multiple customers) available at the moment, but it is prioritized for the upcoming year. We pull Shopify customer tags and allow merchants to use them to create segments.
Learn here how to build segments using Shopify tags.
If you have any questions, don’t hesitate to reach out to [email protected]
Trigger a Yotpo SMS & Email flow with an event from your platform
The Create or Update Custom Customer Event endpoint lets you send custom events that will trigger flows in Yotpo SMS & Email if such events are set up by the merchant.
Some examples of communications that can be sent include reminders for promotions or offers sent in Email, Early access for SMS subscribers, distinguished campaign content, and more.
You can also include any metadata associated with the event to create personalized segments and campaigns. Additionally, you can include any relevant elements in the “event_properties” such as custom URLs, promotion codes, etc, to be used as shortcodes within the SMS.
Once the custom event has been sent, you can follow the below steps to set up an SMS campaign:
- Once you send the event you can access it in the Custom Triggers section of the Yotpo SMS & Email admin (located under Flows & Automations).
- In order to use them in a flow, you’ll need to manually enable the toggle to “Display as a trigger”.
- You can view and edit any flows in the Flows section, located in the same Flows & Automations tab as the Custom Triggers.
Important!
You must send all sample payloads in a Google doc to [email protected].
Once the integration is tested and approved, we will reveal the triggers to all merchants in the flows section of the admin (as opposed to in the custom triggers section).Please also provide us with a start install URL for the integration and a link to the integration help article so we can direct merchants who have not yet installed the integration to be able to do so.
For more detailed information on how to leverage Yotpo SMS & Email flows, check out this guide.
Coming soon
Soon you will be able to include any custom properties associated with the customer for creating personalized segments and campaigns.
You will also be able to build conditional logic leveraging properties sent in "event_properties", but this is on our roadmap for future development.
We highly recommend sending us both the tracking ID and the URL for the custom tracking page to allow merchants to include this in their SMS body.
If you have any questions, don’t hesitate to reach out to [email protected]
Toolkit last update - (April 2023)
Updated 12 months ago