Sailthru Python Library

https://getstarted.meetmarigold.com/engagebysailthru/Content/
Admin
Sailthru Python Library is a client library for accessing the Sailthru REST API, supporting Python...
Tokens:1,007,053
Snippets:7,406
Trust Score:7.5
Update:8 months ago
Show doc for...
Tokens:
Raw
### User Authentication API

Source: https://getstarted.meetmarigold.com/engagebysailthru/Content/developers/api-client/ruby_TocPath=Technical+Documentation%7CFor+Developers%7CAPI+Client+Libraries%7C_____9

This section covers the installation and setup of the Sailthru Ruby client library. It includes instructions for installing the gem, configuring API keys and secrets, and setting up the client object in your Ruby application. It also shows how to increase the default timeout settings.

```APIDOC
## Installation

This client can be installed as a gem. The gem supports Ruby 1.9.3 and above. To install:

```ruby
gem install sailthru-client
```

## Setup

This client library requires the client API key and secret, which can be found in your My Sailthru Settings. To use the ruby client library, add the following code to your application:

```ruby
require 'sailthru'
api_key = '***'
api_secret = '***'
sailthru_client = Sailthru::Client.new(api_key, api_secret)
```

To increase timeout from 10 seconds (default) to 30 seconds, replace the above with:

```ruby
require 'sailthru'
api_key = '***'
api_secret = '***'
api_uri = 'https://api.sailthru.com'
proxy_host = nil
proxy_port = nil
opts = {
    :http_read_timeout => 30,
    :http_ssl_timeout => 30,
    :http_open_timeout => 30
}
sailthru_client = Sailthru::Client.new(api_key, api_secret, api_uri, proxy_host, proxy_port, opts)
```

## Version

```ruby
version = Sailthru::VERSION
```
```

--------------------------------

### Install Sailthru Ruby Gem

Source: https://getstarted.meetmarigold.com/engagebysailthru/Content/developers/api-client/ruby_TocPath=Technical+Documentation%7CFor+Developers%7CAPI+Client+Libraries%7C_____9

Installs the Sailthru client library for Ruby using the gem command. This library supports Ruby version 1.9.3 and above.

```bash
gem install sailthru-client
```

--------------------------------

### Get Sailthru Ruby Client Version

Source: https://getstarted.meetmarigold.com/engagebysailthru/Content/developers/api-client/ruby_TocPath=Technical+Documentation%7CFor+Developers%7CAPI+Client+Libraries%7C_____9

Retrieves the currently installed version of the Sailthru Ruby client library.

```ruby
version = Sailthru::VERSION
```

--------------------------------

### Configure JavaScript Tag Options for Spidering and Tagging

Source: https://getstarted.meetmarigold.com/engagebysailthru/Content/site/personalization-engine/pe-setup

This example demonstrates how to append additional parameters to the Sailthru.init function to control page spidering and tag usage for user interest attribution. These settings are per-page, allowing for dynamic configuration across different site sections.

```javascript
<script src="https://ak.sail-horizon.com/spm/spm.v1.min.js"></script><script>Sailthru.init({
  customerId: '<yourID>',
  // Example options:
  // spider: true, // or false, to control page spidering
  // useStoredTags: true, // or false, to use stored tags for interest attribution
  // url: 'https://example.com/page'
});</script>
```

--------------------------------

### GET a User Example

Source: https://getstarted.meetmarigold.com/engagebysailthru/Content/developers/api-client/python_TocPath=Technical+Documentation%7CFor+Developers%7CAPI+Client+Libraries%7C_____8

Example of using the `api_get` function to retrieve user information.

```APIDOC
## GET a User Example

### Description
This example demonstrates how to use `sc.api_get` to retrieve a user's information by their email address.

### Method
```python
response = sc.api_get('user', {'id':'sailthruuser@test.com'})
if response.is_ok():
    print response.get_body()
else:
    print "Error Code " + str(response.get_error().get_error_code())
    print response.get_error().get_message()
```
```

--------------------------------

### Installation and Setup

Source: https://getstarted.meetmarigold.com/engagebysailthru/Content/developers/api-client/python

Instructions for installing the Sailthru Python client library using pip and setting up the client object for API access.

```APIDOC
## Installation

Install the library using pip:

```
pip install sailthru-client
```

## Running Tests (Optional)

Clone the repository and run tests:

```
pip install -r requirements.txt
tox
```

## Defining the Client Object

Initialize the client with your API key and secret:

```python
from sailthru.sailthru_client import SailthruClient

api_key = 'YOUR_API_KEY'
api_secret = 'YOUR_API_SECRET'
sc = SailthruClient(api_key, api_secret)
```
```

--------------------------------

### Testing Dynamic Variables in Preview

Source: https://getstarted.meetmarigold.com/engagebysailthru/Content/messaging/email/html-templates/template-editor_TocPath=Messaging%7CTemplates%7CHTML+Templates%7C_____1

This example shows how to use the 'Test Vars' feature to set temporary variables for previewing dynamic content. It accepts JSON or key-value pairs.

```json
{
  "varNameHere": "testValue"
}
```

```text
name=dave
```

--------------------------------

### POST a Template Example

Source: https://getstarted.meetmarigold.com/engagebysailthru/Content/developers/api-client/python_TocPath=Technical+Documentation%7CFor+Developers%7CAPI+Client+Libraries%7C_____8

Example of using the `api_post` function to create a new template.

```APIDOC
## POST a Template Example

### Description
This example demonstrates how to use `sc.api_post` to create a new template.

### Method
```python
response = sc.api_post('template', {'template':'test template'})
if response.is_ok():
    print response.get_body()
else:
    print "Error Code " + str(response.get_error().get_error_code())
    print response.get_error().get_message()
```
```

--------------------------------

### Installation

Source: https://getstarted.meetmarigold.com/engagebysailthru/Content/developers/api-client/python_TocPath=Technical+Documentation%7CFor+Developers%7CAPI+Client+Libraries%7C_____8

Instructions for installing the Sailthru Python client library using pip.

```APIDOC
## Installation

### Description
Install the Sailthru Python client library using pip.

### Method
```bash
pip install sailthru-client
```
```

--------------------------------

### Fetch Installs Data (Default - Last Month) using Curl

Source: https://getstarted.meetmarigold.com/engagebysailthru/Content/dev-mobile/rest-api/get-stats-installs_TocPath=Technical+Documentation%7CMobile+-+for+developers%7Crest-api%7C_____10

This example demonstrates how to fetch install statistics for the last month using a default curl request. It requires an API key for authentication and sets the 'Accept' header to 'application/json'.

```curl
# Default parameters (Last Month)  
curl -XGET -i -u :$API_KEY -H 'Accept: application/json' https://api.carnivalmobile.com/v6/stats/installs
```

--------------------------------

### Retrieve Total Installs (cURL)

Source: https://getstarted.meetmarigold.com/engagebysailthru/Content/dev-mobile/rest-api/get-stats-total-installs_TocPath=Technical+Documentation%7CMobile+-+for+developers%7Crest-api%7C_____15

This snippet demonstrates how to fetch the total number of application installs using cURL. It shows examples with default parameters (last month) and with custom 'from' and 'to' date parameters. The API key is required for authentication.

```shell
# Default parameters (Last Month)  
curl -XGET -i -u :$API_KEY -H 'Accept: application/json' https://api.carnivalmobile.com/v6/stats/total_installs  
  
# With Parameters for To and From  
curl -XGET -i -u :$API_KEY -H 'Accept: application/json' https://api.carnivalmobile.com/v6/stats/total_installs?from=2015-07-25&to=2015-07-28
```

--------------------------------

### Fetch Installs Data with Date Range using Curl

Source: https://getstarted.meetmarigold.com/engagebysailthru/Content/dev-mobile/rest-api/get-stats-installs_TocPath=Technical+Documentation%7CMobile+-+for+developers%7Crest-api%7C_____10

This example shows how to retrieve install statistics for a specific date range using the 'from' and 'to' parameters with a curl request. The URL should be wrapped in double quotes when parameters are included. It requires an API key for authentication.

```curl
# With Parameters for To and From  
curl -XGET -i -u :$API_KEY -H 'Accept: application/json' "https://api.carnivalmobile.com/v6/stats/installs?from=2015-07-25&to=2015-07-28"
```

--------------------------------

### GET /v6/stats/installs

Source: https://getstarted.meetmarigold.com/engagebysailthru/Content/dev-mobile/rest-api/get-stats-installs_TocPath=Technical+Documentation%7CMobile+-+for+developers%7Crest-api%7C_____10

Fetches installation statistics. Installs are returned as a feed of DateTime objects with counts next to them. These timestamps represent the beginning of an hour period, and the count is the number of installs that happened in that hour.

```APIDOC
## GET /v6/stats/installs

### Description
Retrieves installation statistics as a feed of DateTime objects with associated counts, representing hourly install data.

### Method
GET

### Endpoint
`https://api.carnivalmobile.com/v6/stats/installs`

### Parameters
#### Query Parameters
- **from** (datetime) - Optional - Beginning date for range.
- **to** (datetime) - Optional - End date for range.

### Request Example
```bash
# Default parameters (Last Month)
curl -XGET -i -u :$API_KEY -H 'Accept: application/json' https://api.carnivalmobile.com/v6/stats/installs

# With Parameters for To and From
curl -XGET -i -u :$API_KEY -H 'Accept: application/json' "https://api.carnivalmobile.com/v6/stats/installs?from=2015-07-25&to=2015-07-28"
```

### Response
#### Success Response (200)
- **date** (string) - The timestamp representing the beginning of an hour period.
- **count** (integer) - The number of installs that happened in that hour.

#### Response Example
```json
[
  {
    "date": "2015-07-25T00:00:00.000Z",
    "count": 23543
  },
  {
    "date": "2015-07-26T00:00:00.000Z",
    "count": 66435
  }
]
```

#### Error Responses
- **401 Unauthorized**: Returned if the API key is invalid or missing.
- **403 Forbidden**: Returned if the API client does not have the correct roles.

#### Error Response Examples
```json
{
  "error":"unauthorized"
}
```

```json
{
  "error":"your api client does not have the correct roles"
}
```

### Date Format
This API endpoint uses the ISO 8601 DateTime format. Examples: `2015-07-25` or `2015-07-25T00:00:00.000+00:00`.
```

--------------------------------

### Installation and Initialization

Source: https://getstarted.meetmarigold.com/engagebysailthru/Content/developers/api-client/node-js

Instructions on how to install the Sailthru Node.js client library and initialize it with your API credentials.

```APIDOC
## Installation
```
npm install sailthru-client --save
```

## Initialization
```javascript
var apiKey = '******',
    apiSecret = '*****',
    sailthru = require('sailthru-client').createSailthruClient(apiKey, apiSecret);
```
```

--------------------------------

### Logging 50x API Errors (Example)

Source: https://getstarted.meetmarigold.com/engagebysailthru/Content/dev-mobile/rest-api/getting-started_TocPath=Technical+Documentation%7CMobile+-+for+developers%7Crest-api%7C_____17

This example demonstrates how to log detailed information when encountering 50x errors from the Sailthru Mobile API. It includes essential fields like timestamp, request method, URL, headers, body, and response status/body, which are crucial for debugging and support.

```text
[unique_id] Timestamp: "2017-01-31T13:12:05Z"
						[unique_id] Request_Method: "POST"
						[unique_id] Request_URL: "api.carnivalmobile.com/events"
						[unique_id] Request_Headers: 'Content-Type': 'application/json' 
						[unique_id] Request_Body: { "name": "example", "count": 3 }
						[unique_id] Response_Code: 500 
						[unique_id] Response_Body: "An internal server error was encountered processing your request"
						
```

--------------------------------

### Initialize Sailthru SDK in Simple Mode (JavaScript)

Source: https://getstarted.meetmarigold.com/engagebysailthru/Content/site/site-recommendations/implementation_TocPath=Site%7CSite+Recommendations%7C_____2

This snippet shows the basic initialization of the Sailthru Engage SDK. It requires including the SDK script and calling Sailthru.init with a customer ID. This mode is suitable for straightforward implementations.

```javascript
<script src="https://ak.sail-horizon.com/spm/spm.v1.min.js"></script>  
<script>   Sailthru.init({
       customerId: <customer id>   });
</script>
```

--------------------------------

### Initialize Sailthru Ruby Client

Source: https://getstarted.meetmarigold.com/engagebysailthru/Content/developers/api-client/ruby_TocPath=Technical+Documentation%7CFor+Developers%7CAPI+Client+Libraries%7C_____9

Initializes the Sailthru client library in a Ruby application using API key and secret. It demonstrates basic setup and how to increase the HTTP timeout settings.

```ruby
require 'sailthru'
api_key = '***'
api_secret = '***'
sailthru_client = Sailthru::Client.new(api_key, api_secret)
```

```ruby
require 'sailthru'
api_key = '***'
api_secret = '***'
api_uri = 'https://api.sailthru.com'
proxy_host = nil
proxy_port = nil
opts = {
    :http_read_timeout => 30,
    :http_ssl_timeout => 30,
    :http_open_timeout => 30
}
sailthru_client = Sailthru::Client.new(api_key, api_secret, api_uri, proxy_host, proxy_port, opts)
```

--------------------------------

### Sailthru Initialization - Simple Mode

Source: https://getstarted.meetmarigold.com/engagebysailthru/Content/site/site-recommendations/implementation_TocPath=Site%7CSite+Recommendations%7C_____2

Basic initialization of the Sailthru JavaScript library with a customer ID.

```APIDOC
## Sailthru Initialization - Simple Mode

### Description
Initializes the Sailthru JavaScript library in simple mode, requiring only the customer ID.

### Method
JavaScript

### Endpoint
N/A

### Parameters
#### Global JavaScript Object
- **Sailthru.init** (function) - Initializes the Sailthru object.
  - **customerId** (number) - Required - Your unique Sailthru customer ID.

### Request Example
```javascript
<script src="https://ak.sail-horizon.com/spm/spm.v1.min.js"></script>  
<script>   Sailthru.init({
       customerId: <customer id>   });  
</script>
```

### Response
N/A
```

--------------------------------

### Job GET Request - Completed Status

Source: https://getstarted.meetmarigold.com/engagebysailthru/Content/developers/api/job-queries

This JSON object shows an example response from a GET request to the job API after a job has completed. It includes details about the job's execution, such as creation time, start and stop times, and the final status. For export jobs, this response would also contain a filename and export_url.

```json
{
  "_id" : ObjectId('4fc7f24a6a44a14b0b0001f1'),
  "class" : "Sail_Job_ListErase",
  "client_id" : 3386,
  "create_time" : new Date('Thu, May 31 2016, 6:35 pm EDT'),
  "create_user" : "example@sailthru.com",
  "job_id" : null,
  "list" : "Sample List",
  "postback_url" : null,
  "queue_time" : new Date('Thu, May 31 2016, 6:35 pm EDT'),
  "remove_count" : 1,
  "report_email" : null,
  "start_time" : new Date('Thu, May 31 2016, 6:36 pm EDT'),
  "stop_time" : new Date('Thu, May 31 2016, 6:36 pm EDT'),
  "time" : 0,
  "status" : "completed"
}
```

--------------------------------

### Initialize Sailthru with Key-Value Targeting (Standard)

Source: https://getstarted.meetmarigold.com/engagebysailthru/Content/site/overlays/create-manage_TocPath=Site%7COverlays%7C_____2

This snippet demonstrates the basic initialization of Sailthru.JS with the `overlayKeyValue` parameter. It assumes a standard website structure where the page reloads on navigation. Ensure Sailthru.JS is installed and you have your customer ID.

```javascript
<script src="https://ak.sail-horizon.com/spm/spm.v1.min.js"></script><script>Sailthru.init({ customerId: '<yourID>', overlayKeyValue: {test_key: "test_value"} });</script>
```

--------------------------------

### Track Sign-up Source with Form Example

Source: https://getstarted.meetmarigold.com/engagebysailthru/Content/content/hosted-pages/build-a-signup-page_TocPath=Content%7CHosted+Pages%7C_____4

This example shows a complete form that includes a hidden input for tracking the sign-up source. The 'source' variable is set to 'contest', allowing sign-ups from this form to be categorized under 'contest' in the Source Report. This illustrates a practical application of source tracking.

```html
<form method="post">    <input type="text" name="email" />    <input type="hidden" name="vars[source]" value="contest" />    <input type="submit" value="Subscribe" /></form>
```

--------------------------------

### Example: GET a User in Python

Source: https://getstarted.meetmarigold.com/engagebysailthru/Content/developers/api-client/python

Demonstrates how to retrieve user information using the `api_get` method with a user ID. It includes checking the response and printing user data or error information.

```python
response = sc.api_get('<span class="mc-variable MyVariables.User_lower variable">user</span>', {'id':'sailthruuser@test.com'})
if response.is_ok():
    print response.get_body()
else:
    print "Error Code " + str(response.get_error().get_error_code())
    print response.get_error().get_message()
```

--------------------------------

### Install Sailthru Java Client via Maven

Source: https://getstarted.meetmarigold.com/engagebysailthru/Content/developers/api-client/java

This snippet shows how to add the Sailthru Java client as a dependency in your Maven project's pom.xml file. Ensure you are using a compatible version.

```xml
<dependency>
    <groupId>com.sailthru.client</groupId>
    <artifactId>sailthru-java-client</artifactId>
    <version>2.4.0</version>
</dependency>
```

--------------------------------

### Sailthru Initialization - Retrieving User Email on Signup Success

Source: https://getstarted.meetmarigold.com/engagebysailthru/Content/site/site-recommendations/implementation_TocPath=Site%7CSite+Recommendations%7C_____2

Initializes Sailthru and configures the `onSignupSuccess` callback to retrieve and utilize the user's email address after a successful signup.

```APIDOC
## Sailthru Initialization - Retrieving User Email on Signup Success

### Description
Initializes the Sailthru JavaScript library and defines a callback function for signup success. This callback allows access to the newly signed-up user's email address for further processing.

### Method
JavaScript

### Endpoint
N/A

### Parameters
#### Global JavaScript Object
- **Sailthru.init** (function) - Initializes the Sailthru object.
  - **customerId** (number) - Required - Your unique Sailthru customer ID.
  - **onSignupSuccess** (function) - Callback function executed upon successful signup.
    - **e** (object) - Event object containing the `email` property of the signed-up user.

### Request Example
```javascript
<script src="https://ak.sail-horizon.com/spm/spm.v1.min.js"></script>  
<script> Sailthru.init({
    customerId: <customer id>,
    onSignupSuccess: function (e) {
    const user_email = e.email;
    //Do something with user_email variable
    }
  });  
</script>
```

### Response
N/A
```

--------------------------------

### Product Example - Create Content Item - Content API

Source: https://getstarted.meetmarigold.com/engagebysailthru/Content/developers/api/content

Example of a POST request to create a product content item with detailed metadata.

```json
{
    "id": "http://example.com/product",
    "key": "url",
    "keys": {
        "sku": "123abc"
    },
    "title": "Product Name Here",
    "description": "Product info text goes here.",
    "price": 2099,
    "inventory": 42,
    "date": "2016-06-20 14:30:00 -0400",
    "tags": "blue, jeans, size-m",
    "vars": {
        "var1": "var 1 value"
    },
    "images": {
        "full": {
            "url": "http://example.com/images/product.jpg"
        }
    },
    "site_name": "Store"}
```

--------------------------------

### GET /v6/stats/total_installs

Source: https://getstarted.meetmarigold.com/engagebysailthru/Content/dev-mobile/rest-api/get-stats-total-installs_TocPath=Technical+Documentation%7CMobile+-+for+developers%7Crest-api%7C_____15

Fetches the total number of application installs. You can optionally provide a 'from' and 'to' date to filter the results within a specific range. If no dates are provided, it defaults to the last month.

```APIDOC
## GET /v6/stats/total_installs

### Description
Retrieves the total number of application installs. Supports filtering by date range.

### Method
GET

### Endpoint
`https://api.carnivalmobile.com/v6/stats/total_installs`

### Parameters
#### Query Parameters
- **from** (datetime) - Optional - Beginning date for the range (ISO 8601 format).
- **to** (datetime) - Optional - End date for the range (ISO 8601 format).

### Request Example
```bash
# Default parameters (Last Month)
curl -XGET -i -u :$API_KEY -H 'Accept: application/json' https://api.carnivalmobile.com/v6/stats/total_installs

# With Parameters for To and From
curl -XGET -i -u :$API_KEY -H 'Accept: application/json' "https://api.carnivalmobile.com/v6/stats/total_installs?from=2015-07-25&to=2015-07-28"
```

### Response
#### Success Response (200)
- **total_installs** (integer) - The total count of installs.

#### Response Example
```json
{
  "total_installs": 593
}
```

#### Error Responses
- **401 Unauthorized**
  ```json
  {
    "error": "unauthorized"
  }
  ```
- **403 Forbidden**
  ```json
  {
    "error": "your api client does not have the correct roles"
  }
  ```

### Date Format
ISO 8601 DateTime format (e.g., `2015-07-25` or `2015-07-25T00:00:00.000+00:00`).

### Caveats
The range granularity is days. `from` is rounded down to the beginning of the day, and `to` is rounded up to the end of the day.
```

--------------------------------

### Get Sailthru Blast Statistics

Source: https://getstarted.meetmarigold.com/engagebysailthru/Content/developers/api-client/ruby_TocPath=Technical+Documentation%7CFor+Developers%7CAPI+Client+Libraries%7C_____9

Retrieves statistics for a specific blast or aggregated statistics for all blasts within a given date range. Requires either a blast ID or start and end dates.

```ruby
response = sailthru_client.stats_blast(8436709)
```

```ruby
response = sailthru_client.stats_blast(nil, '2016-12-01', '2016-12-29')
```

--------------------------------

### Initialize Sailthru in Custom Mode (JavaScript)

Source: https://getstarted.meetmarigold.com/engagebysailthru/Content/site/site-recommendations/implementation_TocPath=Site%7CSite+Recommendations%7C_____2

Include this script to initialize Sailthru with custom settings. Set `isCustom` to true and replace `<ID>` with your Customer ID. Additional parameters can be configured as needed.

```javascript
<script src="https://ak.sail-horizon.com/spm/spm.v1.min.js"></script><script>Sailthru.init({
    customerId: <ID>,
    isCustom: true,
    <additional parameters and values - see init function table in this doc> });
</script>
```

--------------------------------

### Initialize Sailthru with Key-Value Targeting (SPA)

Source: https://getstarted.meetmarigold.com/engagebysailthru/Content/site/overlays/create-manage_TocPath=Site%7COverlays%7C_____2

This snippet shows how to initialize Sailthru.JS for Single Page Applications (SPAs) using the `overlayKeyValue` parameter. SPAs do not reload on navigation, so this configuration helps maintain Sailthru's context. Ensure Sailthru.JS is installed and you have your customer ID.

```javascript
<script src="https://ak.sail-horizon.com/spm/spm.v1.min.js"></script>  
<script>Sailthru.init({hostWebsiteType:"spa", customerId: '<yourID>', overlayKeyValue: {test_key: "test_value"} });</script>
```

--------------------------------

### Example: POST a Template in Python

Source: https://getstarted.meetmarigold.com/engagebysailthru/Content/developers/api-client/python

Demonstrates how to use the `api_post` method to create a new template in Sailthru. It includes checking the response for success and printing the body or error details.

```python
response = sc.api_post('template', {'template':'test template'})
if response.is_ok():
    print response.get_body()
else:
    print "Error Code " + str(response.get_error().get_error_code())
    print response.get_error().get_message()
```

--------------------------------

### Get All Triggers (API GET)

Source: https://getstarted.meetmarigold.com/engagebysailthru/Content/developers/api/trigger_TocPath=Technical+Documentation%7CFor+Developers%7CAPI+Endpoints%7C_____20

Example of retrieving all triggers in the system using the Sailthru API GET method. No parameters are required to fetch all triggers.

```http
GET https://api.sailthru.com/trigger
```

--------------------------------

### Sailthru PHP5 Client Installation

Source: https://getstarted.meetmarigold.com/engagebysailthru/Content/developers/api-client/php5

Instructions for installing the Sailthru PHP5 client library using Composer or from GitHub.

```APIDOC
## Installation

### Composer
If using composer, you can install the library from CLI:
```
composer require sailthru/sailthru-php5-client
```

### GitHub
For other installations, the library can be found on github.
```
Tokens:
Raw