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

Email

  • 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

  1. After the extension is installed, log in to your Magento Admin Panel.
  2. From the System menu, select Configuration.
  3. 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.
  4. To enable the extension:
    • In the Enable/Disable section, set Sailthru by Marigold Module Enabled to Yes.
  5. 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.
  6. 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.
  7. 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.
  8. 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.
If you enable any of these features by setting them to Yes, additional configuration options are displayed.

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.
 

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. 

FieldDescriptionType
magento_idMagento IDinteger
nameFull namestring
suffixName suffixstring
prefixName prefixstring
firstNameFiirst namestring
middleNameMiddle namestring
lastNameLast namestring
storeMagento store namestring
customerGroupMagento customer groupstring
created_dateDate that customer was created in Magentostring (YYYY-MM-DD)
created_timeUNIX timestamp of customer's creation in Magentointeger (Unix Timestamp)
defaultBillingAddressCustomer's primary billing address, with each component accessible as an element within an array. (Seearray
defaultShippingAddressCustomer's primary shipping addressarray

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.

FieldDescriptionTypeAvailable Scope
.nameName associated with addressstringtemplate
.companyCompany associated with addressstringtemplate
.telephoneTelephone associated with addressstringtemplate
.street1Address street 1 fieldstringtemplate
.street2Address street 2 field (apartment, etc)stringtemplate
.cityAddress citystringtemplate, user profile
.stateAddress statestringtemplate, user profile
.state_codeAddress state code (OH, NY)stringtemplate, user profile
.countryAddress countryStringtemplate, user profile
.country_codeAddress country code (US, FR)stringtemplate, user profile
.postal_codeAddress postal codestringtemplate, 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.

FieldDescriptionType
registration.nameName of user registeringString
customerCustomer InfoArray (see user vars)

Order Confirmation

Order confirmations have a var called order, which is an array containing all of the following data:

FieldDescriptionType
order.idIncrement ID (e.g. #000000001)string/int
order.itemsvisible order itemsarray
order.adjustmentsTax, Shipping, and Discount if applicablearray with [title:price] pairs
order.tendersCredit Card type and Amount Orderedsingle [title:price] pair if order used a CC, otherwise null
order.namecustomer namestring
order.statusOrder statusstring
order.stateOrder statestring
order.created_dateMagento CreatedAt date and timeString (e.g. "2017-05-08 23:20:37")
order.totalMagento order grand totalFloat (e.g. 354.7900)
order.subtotalMagento order subtotalFloat (e.g. 354.7900)
order.couponCodeMagento coupon codeString
order.discountdiscount amountFloat (e.g. 354.7900)
order.shippingDescriptionShipping methodString
order.isGuestIs customer a guest?boolean (0 or 1)
order.billingAddressorder billing addressaddress array
order.shippingAddressorder shipping addressaddress array
 

Shipment

Shipment emails contain an order array field (described above) as well as a shipment array field with the properties listed below.

FieldDescrptionType
shipment
shipment.idincrement id (e.g. #10000033)string
shipment.itemsShipment itemsarray of Shipping Item Var Objects
shipment.created_dateMagento CreatedAt date and timeString (e.g. "2017-05-08 23:20:37")
shipment.trackingDetailsArray of tracking objects (e.g. USPS - #123)array with [by:number] pairs
shipment.shipmentItemsShipment itemsarray of Shipping Items
shipment.commentShipment commentstring
shipment.paymentHtmlpayment type Html block from MagentoHTML string
shipment.addressAddress of shipmentaddress object
 

Shipping Items

Shipment items are a simple array of objects that resemble the following

FieldDescriptionType
titleitem namestring
optionsarray of item optionsarray of [label:value] pairs