Salsa Cookbook

Welcome to the Salsa Cookbook! Here you will find examples of commonly used features of the API. All saving and editing options in Salsa also exist via the API.... but it's often challenging to try and remember all of them. Hence the Cookbook.

To get started with the Cookbook, you need to have an account on a Salsa Node. All the calls below are assumed to be prefixed with that node, and assumes that you have authenticated. Some scenarios do not require authentication, see those examples here.

Throughout our documentation you will see URLs like http://sample.nodeurl.tld. Replace this URL with the base portion of your headquarters URL. This could be similar to http://sandbox.salsalabs.org. This references your ACTUAL account. Trying to use your campaign manager with a different node will not work. By default, campaign managers DO NOT have accounts on the sandbox node.

For language specific examples, reference the following links:

Adding a Contact or Supporter

Salsa maintains contacts in an object called 'supporter'. Creating and editing supporters is one of the most commonly used features of Salsa. To create a new supporter: 
http://sample.nodeurl.tld/save?xml&object=supporter&Email=mytestemail@test.com
returns back: 
<success object="supporter" key="2373">Modified entry 2373</success>

By default, when using the save controller, supporters are deduplicated by Email address. All fields in the supporter object are available, just by name, as in all objects. 

http://sample.nodeurl.tld/save?xml&object=supporter&Email=mytestemail@test.com&First_Name=John&Last_Name=Doe&Phone=703-555-5555

Add a Group

Groups are sets of supporters. Adding a supporter to a group involves creating an entry in the "Groups" object, and then tying it to the supporter via the supporter_groups object. Add a new group: 
http://sample.nodeurl.tld/save?xml&object=groups&Group_Name=My Test Group
Returns back a key for that group 
<success object="groups" key="18">Modified entry 18</success>
Add a supporter to a group
http://sample.nodeurl.tld/save?xml&object=supporter_groups&supporter_KEY=2373&groups_KEY=18
where 2373 is the unique supporter key, and 18 is the unique groups key.

Membership in a group is deduplicated -- one supporter can only be in a group once, but can be in as many groups as needed.

Add an offline donation

You may want to add in donation information that may have been obtained elsewhere, either offline or in another system. To do this, make an entry into the donation table, and be sure to specify the supporter_KEY, so that the information can be queried on. To obtain a supporter_KEY, add a supporter as above, and retrieve the KEY from the XML that returns. 
http://sample.nodeurl.tld/save?xml&object=donation&supporter_KEY=2373&amount=15.35&Transaction_Date=2008-08-03&Transaction_Type=Donation

Sending bulk email

When sending more than a few dozen messages, it's important to use the blast email blast system, as that provides for much better performance and statistics than the standard email controller. Blast emails can be scheduled, and provide features for auto-login, tracking open rates and click-through rates, and various other queueing and targeting methods.

Email blast information, such as subject and content, is stored in the email_blast object. Targeting information is stored in the 'query' object, if required.

If no query_KEY is specified in the blast, the email will go to ALL supporters.

Creating a Query

Queries are used as the targeting system for email blasts, or for defining a subset of supporters. Each consists of a main query object, and zero or more query_condition entries for the different conditions. If no conditions are specified, the query will return all supporters. 
http://sample.nodeurl.tld/save?xml&object=query&Name=My Test Group
returns: 
<success object="query" key="222">Modified entry 222</success>
To add a condition to the query: 
http://sample.nodeurl.tld/save?xml&object=query_condition&query_KEY=222&category=groups&table_name=groups&operator=include&value=18
returns: 
<success object="query_condition" key="671">Modified entry 671</success>

Sending an email blast

Sending an email blast immediately requires submitting the content, and an optional query_KEY for targeting. If no query is specified, the blast will go to all supporters. 
http://sample.nodeurl.tld/save?xml&object=email_blast&query_KEY=671&Subject=This is my test email blast&Stage=Pending&HTML_Content=<h2>Test HTML Content</h2>&Text_Content=Test Text Content
returns: 
<success object="email_blast" key="37081">Modified entry 37081</success>
This will send a multi-part email blast message to the supporters who match query #671, which is a query of people in group #18.