Magento 1 Extension v2
Deprecation Notice - Magento 1 Integration
Due to Magento ending support for the Magento 1 platform in June 2020, Sailthru by Marigold will be deprecating its Magento 1 plugin on September 30th, 2020. At deprecation, Sailthru by Marigold will no longer accept new bug requests or plugin issues, The source will remain available for those seeking reference.
For any questions, please reach out to support@sailthru.com.
Sailthru by Marigold's latest extension for Magento 1.x is designed to integrate data and email between your Magento store and Sailthru by Marigold.
This extension is designed to be a turnkey integration for the vast majority of e-commerce stores built on Magento. It can also be used as a framework to extend Magento and Sailthru by Marigold functionality as required. If you are currently using v1 of this extension, see the Migration section in this document. If you are using Magento 2.x, see our compatible extension for that platform version.
Features
- Deliver all Magento-initiated emails through Sailthru by Marigold, benefitting from enhanced deliverability and the user-specific tracking of opens and link clicks.
- Create custom Sailthru by Marigold templates for confirming orders, shipments, customer registration, and newsletter subscription.
Users
- Capture customer purchase data along with Sailthru by Marigold campaign attribution
- Add customers who register or login to your site to a Sailthru by Marigold list of your choice.
- Add customers who sign up for your newsletter to a Sailthru by Marigold list of your choice, hooking into Magento's newsletter module, which allows signups to a single newsletter
- Add or update all Magento customer data in Sailthru by Marigold (for new and existing customers) upon each login, purchase, or name/email update
Personalization
- Sync your products to the Sailthru by Marigold Content Library for all configured stores
- Auto-tag products for Sailthru by Marigold with meta keywords, categories, and product attributes.
- Automatically deploy the Sailthru by Marigold Script Tag, which allows pageview-tracking and Site Personalization Manager. Alternatively, use the Horizon JS for legacy script support, prior to migration to the new Sailthru by Marigold Script Tag.
Migration
If you are currently using v1 of this extension, please reach out to your Customer Success representative to discuss migration strategies before installing v2 in order to ensure compatibility with the following v2 changes:- You must select a template from Sailthru by Marigold for both Abandoned Cart and Order Confirmation.
- The set of fields (a.k.a. vars) that are available for Purchase data has been expanded and existing fields have been renamed. You can find all available order confirmation template vars in this document under Template Vars Reference.
- User fields (a.k.a. vars) have changed. See the Template Vars Reference in this document to view those available in v2.
- If you choose the option to create dynamic "wrapper" email templates to send Magento's fully processed email content, Sailthru by Marigold templates are created for each email type and use {content} and {subject} for the respective var names to introduce that content.
Installation
First, have your developer download the plugin from GitHub. Instructions how to install the plugin are located in the GitHub repository's README. This code is all you need to have basic functionality working.
Setup
Basic Setup
- After the extension is installed, log in to your Magento Admin Panel.
- From the System menu, select Configuration.
- From the side navigation menu, in the Sailthru by Marigold section, click Setup. From the setup page, you will be able to enable the plugin, enter your API key, and choose whether to deploy Sailthru by Marigold Javascript on your store pages.
- To enable the extension:
- In the Enable/Disable section, set Sailthru by Marigold Module Enabled to Yes.
- If you would like all Sailthru by Marigold API calls sent as a result of this integration to be logged in your Magento log:
- In the Enable/Disable section, set API Logging Enabled to Yes. Note: This feature is designed to help developers debug custom functionality, and can expedite help when working with the Sailthru by Marigold Support team on any issues.
- Under API Config, enter the application-specific API Key and API Secret that you requested from your Sailthru by Marigold representative. The API URI is automatically set to https://api.sailthru.com and should not be changed.
- Under JavaScript Deployment, you can specify whether to include a Sailthru by Marigold JavaScript tag on the pages of your store and, if so, which version: the latest Sailthru by Marigold script tag or the legacy Horizon script tag.
- If you already have a Sailthru by Marigold JavaScript tag manually included on your store's pages, leave this setting off until you have removed that tag to avoid duplicate information being recorded to Sailthru by Marigold via multiple tags. Normally, it would then be best to enable this setting to match the version of the Sailthru by Marigold JavaScript you are currently using and to do so immediately upon removing the script from your site in order to prevent any gap in recorded onsite user activity.
- If you choose to use the latest Sailthru by Marigold script tag, you will then be required to enter your Sailthru by Marigold Customer ID, which you can find on the API and Postbacks Settings page in My Sailthru.
- If you select the legacy Horizon script tag, you will then be required to enter your Sailthru by Marigold Horizon Domain, which you can find on the Domains Settings page in My Sailthru.
- In the top-right corner, click Save Config. When the page refreshes, you'll either receive a confirmation notice at the top of the page indicating that the API keys were validated and saved, or an error message if there was a problem.
Transactional Email Delivery
From the Sailthru by Marigold section in the left-side menu, click Transactionals. The Transactionals page has three sections:
- Transactional - When enabled, will send Magento-initiated emails to your users through Sailthru by Marigold--such as order and signup confirmation messages--enhancing deliverability while allowing you to track email clicks and opens.
- Abandoned Cart - When enabled, will automatically send logged-in users a reminder when they have left items in their cart.
- Anonymous Abandoned Cart - When enabled, will automatically send users who are not logged in--but who Sailthru by Marigold has identified as one of your known users due to their Sailthru by Marigold cookie value--a reminder when they have left items in their cart.
Settings for Transactional Email
- Display Sailthru by Marigold email delivery error to customers. When enabled, if there is ever an error with delivering email to a customer--for example, the user has opted out of all mail--enabling this will surface a custom message of your choosing to the customer. If, within the message, you encourage users to contact you and inquire about their email status, this feature can be useful to help catch improperly set opt-outs for customers who still want to receive email.
- Delivery error message - The message displayed to users whose transactional send results in an error, if you have enabled the above option to "display Sailthru by Marigold email delivery error to customers".
- Magento Template Sender - The email address displayed as the Sender for emails sent from Magento using your predefined Magento templates. The menu contains your Sailthru by Marigold-verified sender addresses. If you wish to add another email address, a link is available to bring you to https://my.sailthru.com/verify where you can add new verified emails.
- For any instances of Customer Signup, Newsletter Subscribe, Order Confirmation, or Shipping emails--all the transactional email types that Magento can initiate--you can choose either of the following options. In either case, your email will be sent by Sailthru by Marigold.
- A custom Sailthru by Marigold template: The drop-down alternatively allows you to select from all templates you have configured in Sailthru by Marigold. For each send, data unique to the send is passed from Magento as template vars which you can surface in your template, for example, the shipping address for the order (shipment.address). You can also include user-specific data that is stored on the profile as a user var, such as the user's default shipping address (defaultShippingAddress).
- Use Magento Template: For the given type of email, the associated template that you have configured in Magento will be used. The subject line and content body for each send will be passed to Sailthru by Marigold. Your Sailthru by Marigold account will contain a template--named to match the Magento template and automatically configured by the extension--which simply receives the Magento-rendered subject and body, appends your beacon at the end of the body, and sends the message.
Settings for Abandoned Cart Emails
The Sailthru by Marigold Magento Extension allows you to set up two types of Abandoned Cart message: one for logged-in customers and another for users who have been identified as having a user profile in your Sailthru by Marigold account based on their Sailthru by Marigold cookie value, but who are not logged in. We allow you to configure these separately--for example, using a different time delay or message copy for each--but when configuring either one, the process is the same. Click the Abandoned Cart or Anonymous Abandoned Cart section header to open it, then, next to Enable [or Enable Anonymous] Abandoned Cart Emails, select Yes. After this you will be provided two more fields.
- Abandoned Cart Template - the pre-existing Sailthru by Marigold template to use for your Abandoned Cart sends.
- Abandoned Cart Delay Time - how long to wait before sending the email. For more info on how this works behind the scenes, see the Purchase API documentation.
Content
From the Sailthru by Marigold section in the left-side menu, click Content. This section allows you to enable content hooks so that when you create, update, or delete a product in Magento, its data is updated in your Sailthru by Marigold Content Library. If you wish to perform an initial sync of all product data, see the Job API. To enable this functionality and the additional options below, next to Enable update hooks to send content to Sailthru by Marigold, select Yes. After enabling hooks you must also decide whether to keep master products, variant products, or both, synchronized with Sailthru by Marigold. We define variant products for Magento as simple products that have a parent. For example, the small, blue variant of a shirt. All other product types, including simple products without parents, are considered master products.
- Update Master Products - The extension will add or update each master product in your content library.
- Update Variant Products - The extension will add or update each variant to your content library. For each, Sailthru by Marigold will append a hash mark and variant SKU to its URL. (For example, http://example.com/product1.html#123456789.) This setting also requires that you have selected the Sailthru by Marigold spider option "preserve fragment".
Note: If you have both master and variant products in your Magento database, depending on your requirements and your product type configuration, you may choose to send just master products, just variant products, or both. If you select just variant products or both, work with your Marigold representative to ensure you configure your templates to prevent redundant product recommendations. To better personalize content, Sailthru by Marigold offers auto-tagging of content a Content Library auto-tagger for our Magento extension. This allows you to automatically pull tags from meta keywords (in the meta tab when looking at a product), a product's categories, and a product's attributes (color, size, gender, etc.). You can enable any or all of this functionality.
- Build tags from Meta Keywords
- Build product tags from product categories
- Build product product tags from product attributes
- When you enable building tags from product attributes, a new field appears allowing you to select the attributes that may be used to generate tags. You can select all, but you may also choose them individually if you want to prevent some fields from being used for Sailthru by Marigold tags.
- When you enable building tags from product attributes, a new field appears allowing you to select the attributes that may be used to generate tags. You can select all, but you may also choose them individually if you want to prevent some fields from being used for Sailthru by Marigold tags.
User Management
After you finish configuring how you'd like to sync your content with Sailthru by Marigold, click save, then move on to the users tab. Whenever a user logs-in or registers on your site, they will be added Sailthru by Marigold. However, this screen allows you to customize that further. Enabling Add all customers to a Sailthru by Marigold list will make sure that all customers interacting with your Magento store will be added to a Natural List in Sailthru by Marigold. Additionally, Enable Newsletter Hook allows you to hook into Magento's native subscription system, and make sure that whenever someone signs up to the Magento newsletter, that they are being added a Sailthru by Marigold Natural List of your choice. List options for both options are auto-populated from Sailthru by Marigold.
You can configure Sailthru by Marigold's Lifecycle Optimizer to take action each time a user is added to one of those lists, beginning a welcome flow or taking any other available actions of your choosing.
User Profile Custom Fields (Vars) Reference
When a user signs up to your Magento store or logs in for the first time after the extension is installed, the following data from the user's Magento profile is added to their Sailthru by Marigold user profile as custom fields (a.k.a. vars). Note that all fields will then be actionable in Audience Builder, for example, to find users who signed up via Magento within a given date range.
Field | Description | Type |
magento_id | Magento ID | integer |
name | Full name | string |
suffix | Name suffix | string |
prefix | Name prefix | string |
firstName | Fiirst name | string |
middleName | Middle name | string |
lastName | Last name | string |
store | Magento store name | string |
customerGroup | Magento customer group | string |
created_date | Date that customer was created in Magento | string (YYYY-MM-DD) |
created_time | UNIX timestamp of customer's creation in Magento | integer (Unix Timestamp) |
defaultBillingAddress | Customer's primary billing address, with each component accessible as an element within an array. (See | array |
defaultShippingAddress | Customer's primary shipping address | array |
Billing and Shipping Address Array Fields
The defaultShippingAddress and defaultBillingAddress fields (a.k.a. vars) are arrays that you can access from your template code. You can access the entire array by name, or a given element using dot notation (for example, defaultBillingAddress.name). These are useful in shipment and order confirmations. Note that some of these items are also added to the user profile, for future use when communicating with the customer or segmenting with Audience Builder.
Field | Description | Type | Available Scope |
.name | Name associated with address | string | template |
.company | Company associated with address | string | template |
.telephone | Telephone associated with address | string | template |
.street1 | Address street 1 field | string | template |
.street2 | Address street 2 field (apartment, etc) | string | template |
.city | Address city | string | template, user profile |
.state | Address state | string | template, user profile |
.state_code | Address state code (OH, NY) | string | template, user profile |
.country | Address country | String | template, user profile |
.country_code | Address country code (US, FR) | string | template, user profile |
.postal_code | Address postal code | string | template, user profile |
Template Vars Reference
The extension can automatically send all of your emails that are initiated by Magento through Sailthru by Marigold, dynamically creating templates in Sailthru by Marigold that act as containers for the fully processed email content--subject line and body-- coming from Magento. Beyond those Magento-rendered emails, we also offer the ability to create templates in Sailthru by Marigold for Newsletter Signup, Customer Registration, Order Confirmation, and Shipments. If you create your own custom templates in Sailthru by Marigold, You can use the var names in this section within those templates to surface user information that was recorded by Magento and added to Sailthru by Marigold by the extension.
The extension can automatically send all of your emails that are initiated by Magento through Sailthru by Marigold, dynamically creating templates in Sailthru by Marigold that act as containers for the fully processed email content--subject line and body-- coming from Magento. Beyond those Magento-rendered emails, we also offer the ability to create templates in Sailthru by Marigold for Newsletter Signup, Customer Registration, Order Confirmation, and Shipments. If you create your own custom templates in Sailthru by Marigold, You can use the var names in this section within those templates to surface user information that was recorded by Magento and added to Sailthru by Marigold by the extension.
The extension can automatically send all of your emails that are initiated by Magento through Sailthru by Marigold, dynamically creating templates in Sailthru by Marigold that act as containers for the fully processed email content--subject line and body-- coming from Magento. Beyond those Magento-rendered emails, we also offer the ability to create templates in Sailthru by Marigold for Newsletter Signup, Customer Registration, Order Confirmation, and Shipments. If you create your own custom templates in Sailthru by Marigold, You can use the var names in this section within those templates to surface user information that was recorded by Magento and added to Sailthru by Marigold by the extension.
Newsletter Signup
The email Magento sends when someone subscribes via the Magento Newsletter module. This template only has an email variable, as a customer may sign up without registering. However, if a customer is registering as well, the standard registration vars will be available on the user profile.
Customer Registration
This is the email Magento sends when a customer registers.
Field | Description | Type |
registration.name | Name of user registering | String |
customer | Customer Info | Array (see user vars) |
Order Confirmation
Order confirmations have a var called order, which is an array containing all of the following data:
Field | Description | Type |
order.id | Increment ID (e.g. #000000001) | string/int |
order.items | visible order items | array |
order.adjustments | Tax, Shipping, and Discount if applicable | array with [title:price] pairs |
order.tenders | Credit Card type and Amount Ordered | single [title:price] pair if order used a CC, otherwise null |
order.name | customer name | string |
order.status | Order status | string |
order.state | Order state | string |
order.created_date | Magento CreatedAt date and time | String (e.g. "2017-05-08 23:20:37") |
order.total | Magento order grand total | Float (e.g. 354.7900) |
order.subtotal | Magento order subtotal | Float (e.g. 354.7900) |
order.couponCode | Magento coupon code | String |
order.discount | discount amount | Float (e.g. 354.7900) |
order.shippingDescription | Shipping method | String |
order.isGuest | Is customer a guest? | boolean (0 or 1) |
order.billingAddress | order billing address | address array |
order.shippingAddress | order shipping address | address array |
Shipment
Shipment emails contain an order array field (described above) as well as a shipment array field with the properties listed below.
Field | Descrption | Type |
shipment | ||
shipment.id | increment id (e.g. #10000033) | string |
shipment.items | Shipment items | array of Shipping Item Var Objects |
shipment.created_date | Magento CreatedAt date and time | String (e.g. "2017-05-08 23:20:37") |
shipment.trackingDetails | Array of tracking objects (e.g. USPS - #123) | array with [by:number] pairs |
shipment.shipmentItems | Shipment items | array of Shipping Items |
shipment.comment | Shipment comment | string |
shipment.paymentHtml | payment type Html block from Magento | HTML string |
shipment.address | Address of shipment | address object |
Shipping Items
Shipment items are a simple array of objects that resemble the following
Field | Description | Type |
title | item name | string |
options | array of item options | array of [label:value] pairs |