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.
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.
API URL has the following format
http://app.gotocampaign.com/<api-name>?apikey=<api-key>¶ms
Where api-name is the name of the API you would like to invoke.
Supported APIs are
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
For Serialized JSON, use:
http://app.gotocampaign.com/<api-name>?apikey=<api-key>&output=json¶ms
For Serialized XML, use:
http://app.gotocampaign.com/<api-name>?apikey=<api-key>&output=xml¶ms
Note: XML is the default.
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"}
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.
|
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>
|
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>
|
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>
|
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>
|
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>
|
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>
|
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>
|