Use this call to get or set information about one of your users. Users are referenced by a single email address.
https://api.sailthru.com/email
Get information about one of your users.
| Parameter | Description | Example |
|---|---|---|
email | the email address to look up | example@example.com |
| 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 |
getEmail(email)
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 | {"list-a":1,"list-b":1} |
Update information about one of your users, including adding and removing the user from lists.
| Parameter | Description | Example |
|---|---|---|
email | the email address to modify | example@example.com |
| 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 from that list and 0 to remove the user from the list | lists[list-a]=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 |
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 lower-case vars "source" to set sources 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 |
setEmail(email, vars, lists, templates)
Same as GET mode. If send is used, will also return a send_id for the message that was sent.
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 lists they have subscribed to. We've also included the lowercase ''source' vars to make use of the Sailthru Signup Source Reporting. Also see this tutorial.
email=joe@example.com vars[source]=sidebar lists[mylist]=1
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
$sailthru_client->setEmail('joe@example.com', array('name' => 'Joe Schmoe', 'gender' => 'M'));
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[mylist]=0 lists[testlist]=0
$sailthru_client->setEmail('joe@example.com', null, array('mylist' => 0, 'testlist' => 0));