Home

email

Overview

Use this call to get or set information about one of your users. Users are referenced by a single email address.

Also see "user" call, which is a newer release and allows referencing across client keys instead of only email.

Base URL

https://api.sailthru.com/email

GET Mode

Get information about one of your users.

Required Parameters
Parameter Description Example
email the email address to look up 
example@example.com
Optional Parameters
Parameter Description Example
recent_sends Number of recent transactional sends for this email address you'd like to list. Maximum of 10. 
1
recent_blasts Number of recent blasts for this email address you'd like to list. Maximum of 10. 
1
Client Invocation
getEmail(email)
Return Value

Will return a data structure including some or all of the following information:

Field Description Example
verified 1 if the email address is verified, 0 if not (This setting has no system implication and can be used for your own record keeping.) 
1
optout all if the email address has opted out of all email from you, blast if the email address has opted out of only campaign emails, none if not 
none
vars key/value hash of replacement variables specific to this email address 
{"name":"John Doe","gender":"M"}
lists key/value hash; each key is the name of a list that this email address belongs to 
{"list-a":1,"list-b":1}
templates key/value hash; each key is the name of a template that this email address has opted out of 
{"template-a":0,"template-b":0}
lists_signup key/value hash; keys are list names and values are signup dates 
{"MyList":"Thu, 27 Sep 2012 10:58:59 -0400","OtherList":"Tue, 02 Oct 2012 12:39:39 -0400"}

 

POST Mode

Update information about one of your users, including adding and removing the user from lists.

Required Parameters
Parameter Description Example
email the email address to modify

example@example.com
Optional Parameters
Field Description Example
verified 1 to set the email address to verified, 0 to set the email address to unverified (This is a client-based and setting and has no system implications.)

1
optout all to opt the email out of all email from you, blast to opt the email out of all mass mail blasts, none or 0 to opt the user back in (do not do this without user consent)

all
lists key/value hash; each key is the name of a list, and each value is 1 to subscribe the user to that list and 0 to remove the user from the list

lists[MyList]=1

 

"lists":{"MyList":1}

templates

 key/value hash; each key is the name of a template, and each value is 1 to opt the user back in to template delivery and 0 to opt the user out of template delivery

templates[template-a]=0

 

{"email":"joe@example.com",

"templates":{"template-a":0}}
send template name to send to the updated email address (useful for welcome emails)

welcome_user
send_vars key/value hash of replacement variables only for the welcome send

send_vars[password]=temporarypassword
vars key/value hash of replacement variables you want to set or a JSON string. Use source variable to set for Sailthru's Source Reporting.

vars[name]=John Doe

vars={"name":"John Doe"}

vars={"source":"promo1"}
vars["text_only"] Set to 1 if you want this email address to only receive the text only version of emails.

1
sms Set the SMS number that corresponds to this email address, used for sending SMS messages; Must include area code, preferably country code (+1 for U.S.)

+15551234567
twitter Set the user's Twitter username

sailthru

change_email

 Change the user's email address change_email=original email, email=email you wish to change to
Client Invocation
setEmail(email, vars, lists, templates)

See also Store Vars on a User with setEmail

 

Return Value

Same as GET mode. If send is used, will also return a send_id for the message that was sent.

 

Examples

Example #1: Subscribe someone to a mailing list

This is frequently used when a user signs up or adjusts their settings on your site; in this case you would do a POST call with the list(s) they have subscribed to. For example, a list called Main.

{"email":"joe@example.com", "lists":{"Main":1}}

We can also include the variable source to make use of Sailthru Signup Source reporting. Also see setEmail.

email=joe@example.com vars[source]=sidebar lists[Main]=1
PHP Client equivalent
$sailthru_client->setEmail('joe@example.com',array('source' => 'sidebar')),array('mylist' => 1));

Example #2: Update a user's name and other demographic

This is often done when a user completes their profile information on your site; in this case you would do a POST call with an array of their supplied details. Also see this tutorial.

email=joe@example.com vars[name]=Joe Schmoe vars[gender]=M
PHP Client equivalent
$sailthru_client->setEmail('joe@example.com',array('name' => 'Joe Schmoe','gender' => 'M'));

Example #3: Unsubscribe someone from two mailing lists

When users choose to unsubscribe from some of your lists, for example on a profile page, passing zero values for the lists will unsubscribe them from those lists.

email=joe@example.com lists[Main]=0 lists[MyList]=0 
{"email":"joe@example.com", "lists":{"Main":0, "MyList":0}}
PHP Client equivalent
$sailthru_client->setEmail('joe@example.com', null,array('mylist' => 0, 'testlist' => 0));