user API

API Base URL
user https://api.sailthru.com/user
Description
Get or set information about one of your users. Change user key values, add or update custom vars, add or remove users from lists, or retrieve user activity or engagement data. Users are referenced by multiple keys.

GET MODE
Type Parameter Description Example
Required id The key value to look up the user Example
Optional key The key type of the ‘id’ value used to look up the user FURTHER INFORMATION:
key Parameters
Example
Optional fields The fields to return FURTHER INFORMATION:
fields Parameters
Example
Return N/A Returns data consisting of the optional fields you passed.If you do not pass fields, the default return consists of keysvarslists,engagement, and optout. N/A

key
Type Parameter Description Example
key sid The default, Sailthru-specified identifier for a user’s profile Example
key extid A unique, user-specified identifier for a user’s profile (only available if you enable extid lookup) Example
key cookie The Horizon cookie value, stored in sailthru_hid Example
key email The user’s email address Example
key sms The user’s SMS number (only available if you enable SMS) Example
key fb The user’s Facebook ID (only available if you enable Facebook lookup) Example
key twitter The user’s Twitter name (only available if you enable Twitter lookup) Example

fields
Type Parameter Description Example
fields activity View the following recent user activity:

  • open time – The time of the user’s most recent open
  • click time – The time of the user’s most recent click
  • view time – The time of the user’s most recent view
  • log in time – The time of the user’s most recent log in
  • create_time – The time of the user’s profile creation
  • signup_time – The time the user was added to their first list
Example
fields engagement The user’s current engagement level Example
fields keys A list of currently set keys on the user Example
fields lists The normal lists the user is signed up for, with signup dates Example
fields optout_email The current email optout status of the user Example
fields smart_lists The current smart lists the user is part of Example
fields vars The custom vars set on the user Example
fields purchases A list of purchased items the user purchased. Modify the Purchases count to change the number of items returned. For example: “2” would return 2 items. Example
fields device Receive the user’s most used device when opening an email Example
fields purchase_incomplete This allows you to pull all of the details on a user’s last incomplete purchase Example
fields lifetime lifetime message: how many total emails have we sent to the user
lifetime_pv: pageviews a user has accumulated
lifetime_click: total email clicks
lifetime_purchased: number of times a user has made a purchase
lifetime_purchased_price: total amount a user has spent in lifetime with the brand
Example

POST MODE
Type Parameter Description Example
Required id The key value to identify the user Example
Optional key The key type of the ‘id’ value used to identify the user FURTHER INFORMATION:
key Parameters
Example
Optional keys Set some or all of the user keys Example
Optional keysconflict If you attempt to change keys to values that match existing keys already in the database, you create a conflict. You can specify the resolved behavior of the conflict with keysconflict. Valid values:

  • error (Default) – Returns a duplicate error if there are multiple user profiles in the database with matching keys.
  • merge – Merges multiple profiles in the database that have matching keys. The user profile that you are referencing with id is updated with the merged user data/keys. The other duplicate profiles are deleted.
Example
Optional fields The fields to return FURTHER INFORMATION:
fields Parameters
Example
Optional vars Set custom variables on the user Example
Optional lists Add or remove users to lists Example
Optional optout_email Sets email opt-out status. Valid values:

  • none
  • all
  • basic
  • blast
Example
Optional optout_templates Opt a user in or out of a template. Required values:

  • Template name
  • Opt out or in
    • 1 = opt out from specified template OR
    • 0 = opt in to specified template
Example
Optional cookies The cookies parameter accepts the values of Sailthru cookies in order to convert the stored browser session data into user profile data. For instance, the value of the sailthru_cid cookie can be passed to add anonymous browsing data to a user profile once they are identified via login or signup. FURTHER INFORMATION:
cookies Parameters
Example
Return N/A By default, POST mode returns "ok":true Example

key
Type Parameter Description Example
key email The user’s email address Example
key sid The default, Sailthru-specified identifier for a user’s profile Example
key extid A unique user ID that you set (only if you have extid lookup enabled) Example
key sms The user’s SMS number (only if you have SMS enabled) Example
key fb The user’s Facebook ID (only if you have Facebook lookup enabled) Example
key twitter The user’s Twitter name (only if you have Twitter lookup enabled) Example

fields
Type Parameter Description Example
fields activity View the following recent user activity:

  • open time – The time of the user’s most recent open
  • click time – The time of the user’s most recent click
  • view time – The time of the user’s most recent view
  • log in time – The time of the user’s most recent log in
  • create_time – The time of the user’s profile creation
  • signup_time – The time the user was added to their first list
  • last_purchase_time – The time the user last made a purchase
Example
fields engagement The user’s current engagement level Example
fields keys A list of currently set keys on the user Example
fields lists The normal lists the user is signed up for, with signup dates Example
fields optout_email The current email optout status of the user Example
fields smart_lists The current smart lists the user is part of Example
fields vars The custom vars set on the user Example

cookies
Type Parameter Description Example
cookies sailthru_cid Cookie that stores up to 16 recently-visited URLs for anonymous users. When an anonymous user converts (signs up or signs in), the collected data is used to build a user profile (e.g. recommendations). Example

Use Cases

POST – Create a Sailthru User Profile

{"id":"example@example.com","key":"email"}

GET – Request all keys available for a profile

{"id":"example@example.com", "key":"email","fields":{"keys":1}}

GET – Get Current “keys,” “engagement,” and “activity” Information For A User With A SMS Number (1-555-123-4567)

{
    "id":"+15551234567",
    "key":"sms",
    "fields":
        {
            "keys":1,
            "engagement":1,
            "activity":1
        }
}

POST – Add User “example@example.com” To A List Named “All Users”

{
    "id":"example@example.com",
    "key":"email",
    "lists":
        {
            "All Users":1
        }
}

POST – Set The Email Address Of User With Sailthru ID “4e2879472d7acd6d97144f9e” to “example@example.com”

{
    "id":"4e2879472d7acd6d97144f9e",
    "key":"sid",
    "keys":
        {
            "email":"example@example.com"
        }
}

POST – Change An Email Address Of A User By Referencing A Sailthru ID (sid), Using The “keysconflict” Parameter

{
    "id":"4e2879472d7acd6d97144f9e",
    "key":"sid",
    "keys":
        {
            "email":"example@example.com"
        },
    "keysconflict":"merge"
}

POST – Change An Email Address Using The “keysconflict” Parameter

{
    "id":"emailtobeoverwritten@domain.com",
    "key":"email",
    "keysconflict":"merge",
    "keys":
        {
            "email":"newemail@domain.com"
        }
}

POST – Change An Existing SMS Number Using The “keysconflict” Parameter

This changes the existing id to the new sms key.

{
    "id":"9175551212",
    "key":"sms",
    "keys":{"sms":"7775551212"},
    "keysconflict":"merge"
}

POST – Set The Horizon Cookie On A Subscriber When They Sign In To Your Site

First record that your user with id of  joe@example.com has just logged in on your main site. The returned keys will include the cookie you can set on the user (this is included in the examples below).


JSON Example / POST – Set The Horizon Cookie On A Subscriber When They Sign In

{
    "id":"joe@example.com",
    "fields":
        {
            "keys":1
        }
}

PHP Example / POST – Set The Horizon Cookie On A Subscriber When They Sign In

$result = $sailthru->apiPost
    (
        'user', array
            (
                'id' => 'joe@example.com',
                'fields' => array('keys' => 1)
            )
    );
setcookie('sailthru_hid', $result['keys']['cookie']);

Ruby Example / POST – Set The Horizon Cookie On A Subscriber When They Sign In

response = sailthru.api_post
    (
        'user', 
            {
                :id => 'joe@example.com',
                :fields => {
                    :keys => 1
                    
                }
            }
    )
    
cookies['sailthru_hid'] = {
  :domain => ".example.com",
  :value => response['keys']['cookie'],
  :expires => 3.months.from_now
}

# cookies[:key] is specific to Ruby on Rails

Parameter Examples

GET MODE
Type Parameter
Required id
Example
{
    "id":"example@sailthru.com"
}
Description
Retrieves user profile information for the email key provided

GET MODE
Type Parameter
Optional key
Example
{
    "id":"example@sailthru.com",
    "key":<string key type>
}
Description
The key parameter should be included to specify the key type of id. It is not required to specify the key type for an email or sid.

GET MODE
Type Parameter
key sid
Example
{
    "id":"4e2879472d7acd6d97144f9e",
    "key": "sid"
}
Description
Retrieve user profile information using the sid key.

GET MODE
Type Parameter
key extid
Example
{
    "id": "94234",
    "key": "extid"
}
Description
Retrieve user profile information using the extid key.

GET MODE
Type Parameter
key cookie
Example
{
    "id":"e31b80a7bcfc1d474cf1a37d3bfbd7cf2d4d9ae57517130af6",
    "key": "cookie"
}
Description
Retrieve user profile information using the Horizon cookie value stored in the sailthru_hid browser cookie.

GET MODE
Type Parameter
key email
Example
{
    "id":"example@sailthru.com",
    "key": "email"
}
Description
Retrieve user profile information using the email key.

GET MODE
Type Parameter
key sms
Example
{
    "id":"+15551234567",
    "key": "sms"
}
Description
Retrieve user profile information using the sms key.

GET MODE
Type Parameter
key fb
Example
{
    "id":"279352494051",
    "key": "fb"
}
Description
Retrieve user profile information using the fb key.

GET MODE
Type Parameter
key twitter
Example
{
    "id":"sailthru",
    "key": "twitter"
}
Description
Retrieve user profile information using the twitter key.

GET MODE
Type Parameter
Optional fields
Example
{
    "id":"example@sailthru.com",
    "key":"email",
    "fields":<object fields>
}
Description
Retrieve additional user information specifying specific fields to return (examples below).

GET MODE
Type Parameter
fields activity
Example
{
    "id":"example@sailthru.com",
    "key":"email",
    "fields":
        {
            "activity":1
        }
}
Description
Retrieve user information, including an activity history.

GET MODE
Type Parameter
fields engagement
Example
{
    "id":"example@sailthru.com",
    "key":"email",
    "fields":
        {
            "engagement":1
        }
}
Description
Retrieve user information, including engagement level.

GET MODE
Type Parameter
fields keys
Example
{
    "id":"example@sailthru.com",
    "key":"email",
    "fields":
        {
            "keys":1
        }
}
Description
Retrieve user information, including all user keys.

GET MODE
Type Parameter
fields lists
Example
{
    "id":"example@sailthru.com",
    "key":"email",
    "fields":
        {
            "lists":1
        }
}
Description
Retrieve user information, including all user lists.

GET MODE
Type Parameter
fields optout_email
Example
{
    "id":"example@sailthru.com",
    "key":"email",
    "fields":
        {
            "optout_email":1
        }
}
Description
Retrieve user information, including optout status.

GET MODE
Type Parameter
fields smart_lists
Example
{
    "id":"example@sailthru.com",
    "key":"email",
    "fields":
        {
            "smart_lists":1
        }
}
Description
Retrieve user information, including all smart lists.

GET MODE
Type Parameter
fields purchases
Example
{
    "id":"example@sailthru.com",
    "key":"email",
    "fields":
        {
            "purchases":2
        }
}
Description
Retrieve the past two purchased items that a user purchased. This can work with any count!

GET MODE
Type Parameter
fields device
Example
{
    "id":"example@sailthru.com",
    "key":"email",
    "fields":
        {
            "device":1
        }
}
Description
Return the user’s most used device (based on user opens).

GET MODE
Type Parameter
fields lifetime
Example
{
    "id":"example@sailthru.com",
    "key":"email",
    "fields":
        {
            "lifetime":1
        }
}
Description
Return the total number of messages, pageviews, clicks, purchases and revenue a user has driven in their lifetime.

GET MODE
Type Parameter
fields purchase_incomplete
Example
{
    "id":"example@sailthru.com",
    "key":"email",
    "fields":
        {
            "purchase_incomplete":1
        }
}
Description
Receive all of the details regarding a user’s last incomplete purchase (abandoned cart).

GET MODE
Type Parameter
fields vars
Example
{
    "id":"example@sailthru.com",
    "key":"email",
    "fields":
        {
            "vars":1
        }
}
Description
Retrieve user information, including user vars.

POST MODE
Type Parameter
Required id
Example
{
    "id":"example@sailthru.com"
}

Avoid passing the same value twice in both the ‘id’ and ‘keys’ fields, as this can cause longer processing times. Instead, use this structure:
POST {“id”:”example@example.com“, “key”:”email”,”fields”:{“keys”:1}}

The ‘id’ parameter is required. However, it can be any of the keys, as long as you specify which one you’re using. See key types here.

POST MODE
Type Parameter
Optional key
Examples
{
    "id":"example@sailthru.com",
    "key":<string key type>
}
Description
The key parameter should be included to specify the key type of id. It is not required to specify the key type for an email or sid.

POST MODE
Type Parameter
key email
Example
{
    "id":"example@sailthru.com",
    "key": "email"
}
Description
Post additional user profile information using the email key.

POST MODE
Type Parameter
key sid
Example
{
    "id":"4e2879472d7acd6d97144f9e",
    "key": "sid"
}
Description
Post additional user profile information using the sid key.

POST MODE
Type Parameter
key extid
Example
{
    "id": "987654",
    "key":"extid"
}
Description
Post additional user profile information using the extid key.

POST MODE
Type Parameter
key sms
Example
{
    "id":"+15551234567",
    "key": "sms"
}
Description
Post additional user profile information using the sms key.

POST MODE
Type Parameter
key fb
Example
{
    "id":"279352494051",
    "key": "fb"
}
Description
Post additional user profile information using the fb key.

POST MODE
Type Parameter
key twitter
Example
{
    "id":"sailthru",
    "key": "twitter"
}
Description
Post additional user profile information using the twitter key.

POST MODE
Type Parameter
Optional keys
Example
{
    "id":"example@sailthru.com",
    "keys":
        {
            "twitter":"sailthru",
            "extid" : "ABC123"
        }
}
Description
Post additional user profile keys to a user with an existing email.

POST MODE
Type Parameter
Optional keysconflict
Example
{
    "id":"4e2879472d7acd6d97144f9e",
    "key": "sid",
    "keys":
        {
            "email":"example@sailthru.com"
        },
    "keysconflict":"merge"
}
Description
Post a new email address for a user by referencing their existing sid.

When using keyconflicts and merge, if the email of a hard-bounced profile changes, the status (and any bounce message) will change to that of the profile corresponding to the new email, or to “valid” if no such profile exists.


POST MODE
Type Parameter
Optional fields
Example
{
    "id":"example@sailthru.com",
    "fields": <object fields>
}
Description
Post user information and receive additional data for one or multiple fields in the API return.

POST MODE
Type Parameter
fields activity
Example
{
    "id":"example@sailthru.com",
    "key":"email",
    "fields":
        {
            "activity":1
        }
}
Description
Post user information and receive additional activity data in the API return.

POST MODE
Type Parameter
fields engagement
Example
{
    "id":"example@sailthru.com",
    "key":"email",
    "fields":
        {
            "engagement":1
        }
}
Description
Post user information and receive additional engagement data in the API return.

POST MODE
Type Parameter
fields keys
Example
{
    "id":"example@sailthru.com",
    "key":"email",
    "fields":
        {
            "keys":1
        }
}
Description
Post user information and receive all user profile keys in the API return.

POST MODE
Type Parameter
fields lists
Example
{
    "id":"example@sailthru.com",
    "key":"email",
    "fields":
        {
            "lists":1
        }
}
Description
Post user information and receive all user lists in the API return.

POST MODE
Type Parameter
fields optout_email
Example
{
    "id":"example@sailthru.com",
    "key":"email",
    "fields":
        {
            "optout_email":1
        }
}
Description
Post user information and receive the user’s optout status in the API return.

POST MODE
Type Parameter
fields smart_lists
Example
{
    "id":"example@sailthru.com",
    "key":"email",
    "fields":
        {
            "smart_lists":1
        }
}
Description
Post user information and receive all user smart_lists in the API return.

POST MODE
Type Parameter
fields vars
Example
{
    "id":"example@sailthru.com",
    "key":"email",
    "fields":
        {
            "vars":1
        }
}
Description
Post user information and receive all user vars in the API return.

POST MODE
Type Parameter
Optional vars
Example
{
    "id":"example@sailthru.com",
    "vars":
        {
            "gender":"m",
            "dob":19800527
        }
}
Description
Post vars to a user profile.

POST MODE
Type Parameter
Optional lists
Example
{
    "id":"example@sailthru.com",
    "lists":
        {
            "JoinList":1,
            "RemoveList":0
        }
}
Description
Add / Remove a user from lists.

POST MODE
Type Parameter
Optional optout_email
Example
{
    "id":"example@sailthru.com",
    "optout_email":"all"
}
Description
Change a user’s optout status.

POST MODE
Type Parameter
Optional optout_templates
Example
{
    "id":"example@sailthru.com",
    "optout_templates":
    {
        "Template Name":1        
    }        
}
Description
Opt a user out of or in to a specified template.

  • 1 = opt out from template
  • 0 = opt in to template

POST MODE
Type Parameter
Optional cookies
Example
{
    "id":"example@example.com",
    "cookies": <object cookies>
}
Description
Post data from Sailthru browser cookies to a user profile.

POST MODE
Type Parameter
cookies sailthru_cid
Example
{
    "id":"example@example.com",
    "cookies":
        {
            "sailthru_cid":"U9JEVqLefidFAAAA"
        }
}
Description
Post anonymous Horizon browsing data collected in the sailthru_cid browser cookies to a new user profile.

If you pass in the fields parameter, you can retrieve data from the updated user record, which can prevent you from having to make a POST followed by a GET.

POST MODE
Type Parameter
Return N/A
Example
{
    "ok":true
}
Top