webservices

Scheduling and Sending a Campaign

by Administrator on ‎03-25-2011 10:09 AM

The ability to deliver emails to a large group of people based on our reputation is a capability that we value dearly.  We offer the ability to schedule and send campaigns through API, but this functionality is not available to everyone publicly.  Instead, you need to be given a special permission from our AppConnect team in order to use this API.  The requirements are not stringent; we just want to make sure that you are a legitimate sender and your use case does not hurt our reputation in order to ensure that we can continue to offer best-in-class deliverability for all of our customers' emails. 

 

If you are interested in API for sending and scheduling campaigns in your application or integration, please email the AppConnect support team, who will provide you with access to the Scheduling API.  We need your Constant Contact username and API Key to process the request.

 

Schedule Campaign API


Constant Contact provides an API to schedule a campaign programmatically. Once you create a valid campaign, either through the UI or API, you can use this API to schedule one.

 

Scheduling a Campaign / Re-sending a Campaign


In order to schedule a campaign, you can create a schedule for a particular campaign by issuing a POST method to the following URI:

 

https://api.constantcontact.com/ws/customers/{username}/campaigns/{campaign-id}/schedules

 

You can take the following XML as a starting point and modify it with your parameters:

 

<?xml version='1.0' encoding='UTF-8'?> 
<entry xmlns="http://www.w3.org/2005/Atom"> 
<link href="/ws/customers/joesflowers/campaigns/1100551463584/schedules/1" rel="edit" /> 
<id>http://api.constantcontact.com/ws/customers/joesflowers/campaigns/1100551463584/schedules/1</id>
<title type="text">2010-11-13T15:03:35Z</title> 
<updated>2010-11-13T20:03:35.000Z</updated> 
<author> 
<name>Constant Contact</name> 
</author> 
<content type="application/vnd.ctct+xml"> 
<Schedule xmlns="http://ws.constantcontact.com/ns/1.0/" id="http://api.constantcontact. 
com/ws/customers/joesflowers/campaigns/1100551463584/schedules/1"> 
<ScheduledTime>2010-11-13T20:03:35.000Z</ScheduledTime> 
</Schedule> 
</content> 
</entry> 

 

The only elements you need to modify are the {campaign-id} portion of the URI in <Schedule> and the time used in <ScheduledTime> to reflect your desired schedule time.

 

In order to schedule a campaign, your account must in good standing. You can only schedule a campaign if the campaign is in DRAFT or SENT status. Once the campaign is sent, the schedule resource is automatically deleted, and when you query schedules collection, there will not be any entry.

 

The time you specify in <ScheduledTime> will be used to determine when the campaign is submitted to be sent out. Emails typically begin sending within 1 hour of the time selected, though we try hard to make sure the campaign is sent out as close to the scheduled time as possible.

To send the campaign again, you can use the above POST method again to schedule it again. The campaign will be sent to any contacts that have been added to the contact lists since the last time the campaign was sent. Please note that you can only re-send campaigns whose original sent date is less than 90 days old.

 

There is no functionality to send "now" as it is in the UI. Since we do not allow specifying a time in the past, please add enough buffer to the time you pass through API to account for time differences between servers. We recommend scheduling no sooner than 15 minutes after the request is sent.

 

Updating a Campaign Schedule


In order to update a campaign's schedule when it is in SCHEDULED state, you have two options. You can either cancel the schedule and schedule it again, or you can use PUT on the following URI with your change:

 

https://api.constantcontact.com/ws/customers/{username}/campaigns/{campaign-id}/schedules/{schedule-...

  

Cancelling a Schedule


To cancel a schedule, you can use the DELETE method on the following URI:

 

https://api.constantcontact.com/ws/customers/{username}/campaigns/{campaign-id}/schedules/{schedule-...

  

Campaign Schedule Resource


You can use the schedule resource to send and resend a campaign. Each campaign resource has schedules collection, and by creating a new schedule under this collection, you can set a schedule for a campaign.

 

Schedules Collection


Each campaign has schedules collection, which represents all the schedule-related data for a campaign. Currently, we only support one schedule under this collection, which represents the current schedule.


Request Format

 

GET https://api.constantcontact.com/ws/customers/{username}/campaigns/{campaign-id}/schedules

  

The GET request returns all entries of schedules under schedules collection.

 

Response Format

 

<?xml version='1.0' encoding='UTF-8'?> 
<feed xmlns="http://www.w3.org/2005/Atom"> 
<id>http://api.constantcontact.com/ws/customers/joesflowers/campaigns/1100551463584/schedules</id> 
<title type="text">Schedules for customer: joesflowers</title> 
<link href="schedules" /> 
<link href="schedules" rel="self" /> 
<author> 
<name>joesflowers</name> 
</author> 
<updated>2009-12-04T21:14:12.827Z</updated> 
<link href="/ws/customers/joesflowers/campaigns/1100551463584/schedules" rel="current" /> 
<link href="/ws/customers/joesflowers/campaigns/1100551463584/schedules" rel="first" /> 
<entry> 
<link href="/ws/customers/joesflowers/campaigns/1100551463584/schedules/1" rel="edit" /> 
<id>http://api.constantcontact.com/ws/customers/joesflowers/campaigns/1100551463584/schedules/1</id>
<title type="text">2010-11-13T15:03:35Z</title> 
<updated>2010-11-13T20:03:35.000Z</updated> 
<author> 
<name>Constant Contact</name> 
</author> 
<content type="application/vnd.ctct+xml"> 
<Schedule xmlns="http://ws.constantcontact.com/ns/1.0/" id="http://api.constantcontact. 
com/ws/customers/joesflowers/campaigns/1100551463584/schedules/1"> 
<ScheduledTime>2010-11-13T20:03:35.000Z</ScheduledTime> 
</Schedule> 
</content> 
</entry> 
</feed> 

 

Request Format

 

POST https://api.constantcontact.com/ws/customers/{username}/campaigns/{campaign-id}/schedules

  

For more detailed information about how to schedule a campaign, please refer to Scheduling a Campaign. For more details on the URI, refer to the URI Format description.


The XML below will allow you to post to schedules collection.

 

<?xml version='1.0' encoding='UTF-8'?> 
<entry xmlns="http://www.w3.org/2005/Atom"> 
<link href="/ws/customers/joesflowers/campaigns/1100551463584/schedules/1" rel="edit" /> 
<id>http://api.constantcontact.com/ws/customers/joesflowers/campaigns/1100551463584/schedules/1</id>
<title type="text">2010-11-13T15:03:35Z</title> 
<updated>2010-11-13T20:03:35.000Z</updated> 
<author> 
<name>Constant Contact</name> 
</author> 
<content type="application/vnd.ctct+xml"> 
<Schedule xmlns="http://ws.constantcontact.com/ns/1.0/" id="http://api.constantcontact. 
com/ws/customers/joesflowers/campaigns/1100551463584/schedules/1"> 
<ScheduledTime>2010-11-13T20:03:35.000Z</ScheduledTime> 
</Schedule> 
</content> 
</entry> 

 

Schedule Resource


The schedule resource represents an individual schedule of a campaign. Currently, you can only have one schedule resource under schedules collection.

 

Request Format

 

GET https://api.constantcontact.com/ws/customers/{username}/campaigns/{campaign-id}/schedules/{schedule-...

  

Response Format

 

<?xml version='1.0' encoding='UTF-8'?> 
<entry xmlns="http://www.w3.org/2005/Atom"> 
<link href="/ws/customers/joesflowers/campaigns/1100551463584/schedules/1" rel="edit" /> 
<id>http://api.constantcontact.com/ws/customers/joesflowers/campaigns/1100551463584/schedules/1</id>
<title type="text">2010-11-13T15:03:35Z</title> 
<updated>2010-11-13T20:03:35.000Z</updated> 
<author> 
<name>Constant Contact</name> 
</author> 
<content type="application/vnd.ctct+xml"> 
<Schedule xmlns="http://ws.constantcontact.com/ns/1.0/" id="http://api.constantcontact. 
com/ws/customers/joesflowers/campaigns/1100551463584/schedules/1"> 
<ScheduledTime>2010-11-13T20:03:35.000Z</ScheduledTime> 
</Schedule> 
</content> 
<source> 
<id>http://api.constantcontact.com/ws/customers/joesflowers/campaigns/1100551463584/schedules</id> 
<title type="text">Schedules for customer: joesflowers</title> 
<link href="schedules" /> 
<link href="schedules" rel="self" /> 
<author> 
<name>joesflowers</name> 
</author> 
<updated>2009-12-04T21:14:48.439Z</updated> 
</source> 
</entry> 

 

Request Format

 

PUT https://api.constantcontact.com/ws/customers/{username}/campaigns/{campaign-id}/schedules/{schedule-...

  

By using the PUT method, you can modify the existing schedule.

 

Request Format

 

DELETE https://api.constantcontact.com/ws/customers/{username}/campaigns/{campaign-id}/schedules/{schedule-...

  

By deleting a specific schedule resource, you can cancel a schedule for sending a campaign.

 

URI Format Description

 

URI Component Description user-name The account owner's Constant Contact user name. Value must be in lower case. campaigns To find particular campaigns, query the collection by adding one or more query parameters to the collection's URI:

 

campaigns?status=SENT

 

Below are the choices of status for query:


Status                 Description

SENT                  All campaigns that have been sent and not currently scheduled for resend
SCHEDULED   All campaigns that are currently scheduled to be sent some time in the future
DRAFT               All campaigns that have not yet been scheduled for delivery
RUNNING         All campaigns that are currently being processed and delivered