Pulling contacts from an existing database for the purposes of surveying or other otherwise gathering information is one of the most common uses of the SurveyGizmo API. In this use-case example we'll cover how to create a campaign, add contacts, and send the campaign emails.
Step 1: Create a New Campaign
To begin, we'll create a new campaign with a create (PUT) SurveyCampaign call. (We're assuming there is an existing survey.)
https://restapi.surveygizmo.com/v4/survey/123456/surveycampaign?_method=PUT&type=email&name=New%20Campaign
The return will look like the below return. You'll need to parse the return for the id that will be used in the next call.
Notice there is also an inviteid present already. When you create a campaign, using the API or the UI, a default message is created. So, while you might think your next step is to use the EmailMessage object to create a message, you don't need to!
Array
(
[result_ok] => 1
[data] => Array
(
[id] => 1234567
[inviteid] => 123456
[_type] => SurveyCampaign
[_subtype] => email
[__subtype] => standard
[status] => Active
[name] => New Campaign
[uri] => s-12de70-i.sgizmo.com/s3/
[SSL] => False
[tokenvariables] =>
[limit_responses] =>
[close_message] =>
[language] =>
[datecreated] => 2015-12-01 21:15:51
[datemodified] => 2015-12-01 21:15:51
)
)
Step 2: Add Contacts
With your id handy from the create SurveyCampaign call, you'll make a series of create (PUT) contact calls, one for each contact, to add contacts to the newly created campaign using the Contact sub-object.
https://restapi.surveygizmo.com/v4/survey/123456/surveycampaign/1234567/contact?_method=PUT&semailaddress=example@email.com
Step 3: Get Message ID
Once you are finished adding contacts you are ready to customize your email message. When you create a new campaign, a default message is added so you'll need to get the id for this message with an EmailMessage GET call like so:
https://restapi.surveygizmo.com/v4/survey/123456/surveycampaign/1234567/emailmessage?_method=GET
Review the return, make note of your the id as well as the default values/text for the following fields that can be modified via an EmailMessage update (POST):
- from[name]
- from[email]
- replies
- subject
- messagetype
- body[text]
- body[html]
Array
(
[result_ok] => 1
[total_count] => 1
[page] => 1
[total_pages] => 1
[results_per_page] => 1
[data] => Array
(
[0] => Array
(
[id] => 1150520
[_type] => EmailMessage
[_subtype] => message
[messagetype] => plaintext
[medium] => Email
[invite_identity] => 630845
[status] => Building
[from] => Array
(
[email] => surveys@sgizmo.com
[name] => Survey Research
)
[subject] => Help out by taking this survey.
[body] => Array
(
[text] => Hi
I'm currently running a study. If you don't mind, please fill out this survey -- it should only take a few minutes.
[invite("survey link")]
Thank You!
[html] => Hi
I'm currently running a study. If you don't mind, please fill out this survey -- it should only take a few minutes.
Begin
Thank You!
)
[sfootercopy] => This message was sent by [account("physical address")].
To unsubscribe, click below:
[invite("unsubscribe link")]
[datecreated] => 2015-12-04 14:38:35
[datemodified] => 2015-12-04 14:38:35
)
)
)
Step 4: Update Message with Desired Customizations and Set send=true
Your next step will be to update (POST) the message with the EmailMessage object with any of the desired customizations you wish to make to the default message and the send=true parameter (if you are ready to send).
https://restapi.surveygizmo.com/v4/survey/123456/surveycampaign/1234567/emailmessage/1150520?_method=POST&messagetype=html&from[name]=bri&from[email]-bri@sgizmo.com&subject=We%20need%20your%20feedback!&send=true
The return will confirm that the message is sending.
Array
(
[result_ok] => 1
[0] => Sending...
)