DEVELOPER API

Overview

The GoToCampaign API is a way for you to connect your customer database, CRM, CMS, or e-commerce shopping cart with GoToCampaign. It's really powerful stuff. You can extend your application with the power and flexibility of GoToCampaign and let GoToCampaign handle all outbound emails which can be tracked.

Benefits

  • Leverage your existing investment in your application and turn it into a powerful communication platform.
  • Web designers can create private label "client portals" where they can log in and create and execute email campaigns.
  • Add a "Subscribe to Newsletter" option to your e-commerce checkout page.
  • Publishers can add subscription data into GoToCampaign, so that you do not need to import subscribers manually.
  • Link campaign stats to your internal database and create your own reports.
  • Send out a news alert on a product launch. new service offering or support detail.
  • Handle subscriber segmentation (list management) with your CRM application and send marketing or nurturing emails to them.

Basic Details

Our new and improved API will now give you the tools you need to create and manage your campaigns and get stats for your campaigns. You can connect into our API using simple HTTP POST or HTTP GET. Then you can get the data back out in XML or JSON. For large data request, we propose HTTP POST.

These are the functions currently covered by our API:

  • Create Campaign
  • Modify Campaign
  • Add Subscribers to a Campaign
  • Launch Campaign
  • Get Campaign Report
  • Add Subscriber to a List

Submit URL & Parameters

API URL has the following format

http://app.gotocampaign.com/<api-name>?apikey=<api-key>&params

Where api-name is the name of the API you would like to invoke. Supported APIs are

  1. api-campaign-create - Create a new Campaign
  2. api-campaign-modify - Modify an existing Campaign
  3. api-campaign-add-subscriber - Add subscriber to campaign
  4. api-campaign-add-subscribers - Add multiple subscribers to campaign
  5. api-campaign-launch - Launch an existing Campaign in Draft state
  6. api-campaign-report - Get activity report for a Campaign
  7. api-subscribe - Add subscriber to a list

api-key is an unique token for your GoToCampaign account. You can find this key in 'My Profile' screen (find the tab in top right corner of the application) within GoToCampaign application once you log in. Navigate to bottom part of the screen to locate it. This is a permanent key for you and will not change.

params are URL parameters depending on the API you use. See below for more information on supported parameters for each API

Return Format

For Serialized JSON, use:
http://app.gotocampaign.com/<api-name>?apikey=<api-key>&output=json&params

For Serialized XML, use:
http://app.gotocampaign.com/<api-name>?apikey=<api-key>&output=xml&params

Note: XML is the default.

Error Response

In case you passed incorrect/insufficient data or data format is improper, GoToCampaign API returns an error in the following format with a reason text which will help you fix the issue.

XML:
<response>
<error>error reason text here</error>
<status>ERROR</status>
</response>

JSON:
{"error":"error reason text here","status":"ERROR"}
 

API Details

1. Create Campaign
API name api-campaign-create
Definition Create a campaign in Draft state with all necessary details like name, email subject, email html/text body, from email, reply email and campaign schedule and return the campaignId for future use.
URL Format XML
http://app.gotocampaign.com/api-campaign-create?apikey=<api-key>&output=xml&[params]

JSON
http://app.gotocampaign.com/api-campaign-create?apikey=<api-key>&output=json&[params]
URL Parameters

name - Name of the campaign (mandatory)

subject - Subject of the email (mandatory)

html - Email HTML body (either html or text is mandatory)

text - Email TEXT body (either html or text is mandatory)

fromname - Email 'From' name which will be seen in subscriber inbox as the sender

fromemail - Email 'From Email Address' which will be seen in subscriber inbox as the sender email address

replyemail - Email 'ReplyTo' which will recieve all replies by the subscribers

schedule - Campaign start schedule. If not specified, campaign will be started immediately when the api-campaign-launch API is invoked.

  • Date should be in "yyyy-MM-dd HH:mm:ss" format and should be in GMT (UTC).
  • Example: schedule=2010-08-20 10:30:00  for 20th Auguset 2010 10.30 AM GMT
  • Important: Depending on your timezone, you need to convert to GMT
Sample Requests

http://app.gotocampaign.com/api-campaign-create?apikey=xxxxxxxxx&name=MyTestCampaign&subject=MytestSubject&text=TestEmail

http://app.gotocampaign.com/api-campaign-create?apikey=xxxxxxxxx&output=json&name=MyTestCampaign&subject=MytestSubject&html=<b>Test Mail</b>&text=TestMail&schedule=2010-08-20 10:30:00
Sample Response

XML
<response>
<campaignStatus>Draft</campaignStatus>
<campaignId>574</campaignId>
<status>SUCCESS</status>
</response>


JSON
{"campaignStatus":"Draft","campaignId":574,"status":"SUCCESS"}

2. Modify Campaign
API name api-campaign-modify
Definition Modify a campaign with details like name, email subject, email html/text body, from email, reply email and campaign schedule. Schedule can me modified only if the campaign is in Draft state.
URL Format XML
http://app.gotocampaign.com/api-campaign-modify?apikey=<api-key>&output=xml&id=<campaignid>&[params]

JSON
http://app.gotocampaign.com/api-campaign-modify?apikey=<api-key>&output=json&id=<campaignid>&[params]
URL Parameters id - id of an existing campaign (usually created by the api-campaign-create API)

name - Name of the campaign

subject - Subject of the email

html - Email HTML body

text - Email TEXT body

fromname - Email 'From' name which will be seen in subscriber inbox as the sender

fromemail - Email 'From Email Address' which will be seen in subscriber inbox as the sender email address

replyemail - Email 'ReplyTo' which will receive all replies by the subscribers

schedule - Campaign start schedule
Sample Requests

http://app.gotocampaign.com/api-campaign-modify?apikey=xxxxxxxxx&id=574&subject=MyNewSubject

http://app.gotocampaign.com/api-campaign-modify?apikey=xxxxxxxxx&output=json&id=574&schedule=2010-08-22 06:30:00
Sample Response XML
<response>
<campaignStatus>Draft</campaignStatus>
<campaignId>574</campaignId>
<status>SUCCESS</status>
</response>


JSON
{"campaignStatus":"Draft","campaignId":574,"status":"SUCCESS"}

3. Add Subscriber to a Campaign
API name api-campaign-add-subscriber
Definition Add subscriber to a campaign. Campaign can be in any state. If campaign is active, then email is immediately sent to the new subscriber added. A single subscriber is added per API request.
URL Format XML
http://app.gotocampaign.com/api-campaign-add-subscriber?apikey=<api-key>&output=xml&id=<campaignid>&email=[email]&firstname=[fname]&lastname=[lname]&company=[company]

JSON
http://app.gotocampaign.com/api-campaign-add-subscriber?apikey=<api-key>&output=json&id=<campaignid>&email=[email]&firstname=[fname]&lastname=[lname]&company=[company]
URL Parameters id - id of an existing campaign (usually created by the api-campaign-create API). You can also get the API URI with campaign id from the campaign snapshot screen.

email - email addresses

firstname - First name of the subscriber (optional)

lastname - Last name of the subscriber (optional)

company- Company name of the subscriber (optional)
Sample Requests http://app.gotocampaign.com/api-campaign-add-subscriber?apikey=xxxxxxxxx&id=574&email=john@example.com
http://app.gotocampaign.com/api-campaign-add-subscriber?apikey=xxxxxxxxx&id=574&email=john@example.com&fistname=John&lastname=Smith&company=ABCWidgets
Sample Response XML
<response>
<campaignStatus>Draft</campaignStatus>
<campaignId>574</campaignId>
<status>SUCCESS</status>
</response>


JSON
{"campaignStatus":"Draft","campaignId":574,"status":"SUCCESS"}

4. Add Multiple Subscribers to Campaign
API name api-campaign-add-subscribers
Definition Add subscriber emails to a campaign. Campaign can be in any state. If campaign is active, then emails are immediately sent to the new subscribers added. Multiple emails can be passed separated by a comma. Only email can be given for a subscriber. See api-campaign-add-subscriber if you want to pass other fields.
Note: If you want to add large number of emails it is advised to invoke this API multiple times and pass up to 1000 emails in each request to avoid HTTP timeout issues.
URL Format XML
http://app.gotocampaign.com/api-campaign-add-subscribers?apikey=<api-key>&output=xml&id=<campaignid>&emails=[emails]

JSON
http://app.gotocampaign.com/api-campaign-add-subscribers?apikey=<api-key>&output=json&id=<campaignid>&emails=[emails]
URL Parameters id - id of an existing campaign (usually created by the api-campaign-create API)

emails - email addresses separated by comma
Sample Requests http://app.gotocampaign.com/api-campaign-add-subscribers?apikey=xxxxxxxxx&id=574&emails=john@example.com,smith@example.com
Sample Response XML
<response>
<campaignStatus>Draft</campaignStatus>
<campaignId>574</campaignId>
<status>SUCCESS</status>
<count>2</count>
</response>


JSON
{"campaignStatus":"Draft","campaignId":574,"status":"SUCCESS","count":2}

5. Launch Campaign
API name api-campaign-launch
Definition Schedule or start a campaign depending on the schedule set for the campaign. If no schedule is set, campaign will be started immediately and emails will be sent to the subscrbers added to the campaign. if schedule is ste, campaign will be scheduled for that time.
URL Format XML
http://app.gotocampaign.com/api-campaign-launch?apikey=<api-key>&output=xml&id=<campaignid>

JSON
http://app.gotocampaign.com/api-campaign-launch?apikey=<api-key>&output=json&id=<campaignid>
URL Parameters id - id of an existing campaign (usually created by the api-campaign-create API)
Sample Requests http://app.gotocampaign.com/api-campaign-launch?apikey=xxxxxxxxx&id=574
Sample Response XML
<response>
<campaignStatus>Draft</campaignStatus>
<campaignId>574</campaignId>
<status>SUCCESS</status>
<count>2</count>
</response>


JSON
{"campaignStatus":"Draft","campaignId":574,"status":"SUCCESS","count":2}

6. Get Campaign Report
API name api-campaign-report
Definition Get the campaign statistics like emails sent, open, clicks etc.
URL Format XML
http://app.gotocampaign.com/api-campaign-report?apikey=<api-key>&output=xml&id=<campaignid>

JSON
http://app.gotocampaign.com/api-campaign-report?apikey=<api-key>&output=json&id=<campaignid>
URL Parameters id - id of an existing campaign (usually created by the api-campaign-create API)
Sample Requests http://app.gotocampaign.com/api-campaign-report?apikey=xxxxxxxxx&id=574
Sample Response XML
<response>
<status>SUCCESS</status>
<campaignName>My First Campaign</campaignName>
<campaignStatus>Active</campaignStatus>
<campaignId>574</campaignId>
<unsubrate>0.0</unsubrate>
<openrate>0.0</openrate>
<clickrate>0.0</clickrate>
<spamrate>0.0</spamrate>
<uniqueclicks>0</uniqueclicks>
<opens>0</opens>
<unsubs>0</unsubs>
<sent>0</sent>
<clicks>0</clicks>
<bounced>0</bounced>
<uniqueopens>0</uniqueopens>
<notopened>0</notopened>
<spam>0</spam>
</response>


JSON
{"campaignName":"My Test Campaign","campaignStatus":"Active","campaignId":574,"unsubrate":0,
"openrate":0,"status":"SUCCESS","clickrate":0,"spamrate":0,"uniqueclicks":"0","opens":"0","unsubs":"0",
"sent":"0","clicks":"0","bounced":"0","uniqueopens":"0","notopened":"0","spam":"0"}

7. Add Subscriber to a List
API name api-subscribe
Definition Add subscriber to a list.
URL Format XML
http://app.gotocampaign.com/api-subscribe?apikey=<api-key>&output=xml&id=<listid>&email=[email]&firstname=[fname]&lastname=[lname]&company=[company]

JSON
http://app.gotocampaign.com/api-subscribe?apikey=<api-key>&output=json&id=<listid>&email=[email]&firstname=[fname]&lastname=[lname]&company=[company]
URL Parameters id - id of an existing list. You can also get the API URI with list id from the list snapshot screen (bottom right).

email - email addresses

firstname - First name of the subscriber (optional)

lastname - Last name of the subscriber (optional)

company- Company name of the subscriber (optional)
Sample Requests http://app.gotocampaign.com/api-subscribe?apikey=xxxxxxxxx&id=574&email=john@example.com
http://app.gotocampaign.com/api-subscribe?apikey=xxxxxxxxx&id=574&email=john@example.com&fistname=John&lastname=Smith&company=ABCWidgets
Sample Response XML
<response>
<status>SUCCESS</status>
<listId>574</listId>
<prospectId>123</prospectId>
</response>


JSON
{"status":"SUCCESS","listId":574,"prospectId":123}