webservices

Creating a Campaign

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

There are two types of email campaigns in Constant Contact: template-based emails that use email templates provided by Constant Contact and custom-code campaigns that use HTML/XHTML provided by the users, which is equivalent to using "Use My Own Code" option when creating a campaign in Constant Contact.

 

We only provide an ability to create a custom-code campaign through the API.  You can create either an HTML-based campaign or an XHTML-based campaign.  In both cases, you need to provide the details of the campaign you are trying to create, such as subject, from email address, reply-to email address, etc.

To create a campaign, call the following URI with POST method:

 

https://api.constantcontact.com/ws/customers/{user-name}/campaigns 

You also need to ensure that Content-Type HTTP header is set to application/atom+xml.  The body of the request should contain the elements of a campaign, as described in the Campaigns Collection Resource.  The following is the minimal XML required to create a campaign. To create your own campaign, copy this and replace references to 'joesflowers' with your own account information.

 

<?xml version="1.0" encoding="UTF-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <id>http://api.constantcontact.com/ws/customers/joesflowers/campaigns/0</id>
  <title type="text">My first Constant Contact email</title>
  <updated>2011-04-25T13:53:04.243Z</updated>
  <content type="application/vnd.ctct+xml">
    <Campaign xmlns="http://ws.constantcontact.com/ns/1.0/">
      <Name>Created via API</Name>
      <Subject>News from Joe's Flowers</Subject>
      <FromName>Joe's Flowers</FromName>
      <ViewAsWebpage>NO</ViewAsWebpage>
      <PermissionReminder>NO</PermissionReminder>
      <OrganizationName>Joe's Flowers</OrganizationName>
      <OrganizationAddress1>123 Main Streed</OrganizationAddress1>
      <OrganizationAddress2/>
      <OrganizationAddress3/>
      <OrganizationCity>Waltham</OrganizationCity>
      <OrganizationState>MA</OrganizationState>
      <OrganizationInternationalState/>
      <OrganizationCountry>US</OrganizationCountry>
      <OrganizationPostalCode>02452</OrganizationPostalCode>
      <IncludeForwardEmail>NO</IncludeForwardEmail>
      <IncludeSubscribeLink>NO</IncludeSubscribeLink>
      <EmailContentFormat>HTML</EmailContentFormat>
      <EmailContent>&lt;html&gt;          &lt;body&gt;Hello!          &lt;/body&gt;        &lt;/html&gt;</EmailContent>
      <EmailTextContent>Hi There</EmailTextContent>
      <FromEmail>
        <Email id="http://api.constantcontact.com/ws/customers/joesflowers/settings/emailaddresses/1"/>
        <EmailAddress>joe@somedomain.com</EmailAddress>
      </FromEmail>
      <ReplyToEmail>
        <Email id="http://api.constantcontact.com/ws/customers/joesflowers/settings/emailaddresses/1"/>
        <EmailAddress>joe@somedomain.com</EmailAddress>
      </ReplyToEmail>
    </Campaign>
  </content>
  <source>
    <author>
      <name>joesflowers</name>
    </author>
  </source>
</entry>

Because we use the Atom specification for XML, there are several elements that are required even though they are not used by the server and are replaced upon a successful contact creation.  These elements are <id>, <title>, <author>, and <updated> elements. The <id> must contain a URI, but since the value is not used by the server, any URI will work. The server does not check for uniqueness when creating a contact because a new unique ID will be created anyway. The <updated> element must contain a date or date/time value, but again the value is not used by the server.

 

Since the API only supports creating a custom-code campaign, there is no reason to specify <CampaignType>, which will be ignored.

 

You need to ensure to specify the correct value in <EmailContentFormat> element.  If it is set to HTML, then the values in <EmailContent> will be treated like HTML the same was it is treated in our UI.  Since we do not validate the correctness of HTML, you will be able to create a HTML-based campaign with invalid HTML so it is imperative that you ensure your HTML is correct.

 

If it is set to XHTML, then the values in <EmailContent> will be treated like XHTML the same way it is treated in our UI, which means it will be subject to a more strict validation to ensure the XHTML is valid.  If it is not valid, you will receive an error and the campaign will not be created.  In addition, <TextContent> also must have some content in order to create an XHTML campaign.  The content must be in valid XHTML format and any text content you pass in must be enclosed by <Text></Text> tags.

 

<FromEmail> and <ReplyToEmail> must be set with the account's confirmed email addresses and their values must be valid ID's from Account Settings and Email Address Resource.

 

There are three sets of elements that go together:

 

  • <ViewAsWebpage>, <ViewAsWebpageLinkText> and <ViewAsWebpageText>
    If <ViewAsWebpage> is set to 'YES', then values in <ViewAsWebpageLinkText> and <ViewAsWebpageText> will be used, and a link to view the campaign as a webpage will be included in the campaign.  If <ViewAsWebpage> is set to 'NO', then values in the other two elements are not required and will be ignored if present.
  • <IncludeFowardEmail> and <ForwardEmailLinkText>
    If <IncludeFowardEmail> is set to 'YES', then the value in <ForwardEmailLinkText> will be used to insert a link in the campaign.  This is the same as "Forward Email to Friend" feature in the UI.  If <IncludeForwardEmail> is set to 'NO', then <FowardEmailLinkText> is not required and will be ignored.
  • <IncludeSubscribeLink> and <SubscribeLinkText>
    If <IncludeSubscribeLink> is set to 'YES', then the value in <SubscribeLinkText> will be used to insert a link in the forwarded email for "Forward Email to Friend" feature in the UI.  If <IncludeSubscribeLink> is set to 'NO', then <SubscribeLinkText> is not required and will be ignored.

The elements <GreetingSalutation>, <GreetingName> and <GreetingString> ared used to specify how the greeting in the campaign should be set.  <GreetingSalutation> and <GreetingName> are combined to create a recipient-specific greeting; if the value specified in <GreetingName> does not exist for a particular contact, such as missing FirstName, then <GreetingString> will be used.  The valid values for <GreetingName> are 'FirstName', 'LastName', 'FirstAndLastName' or 'NONE'.

 

The user's organization information is represented by <OrganizationName>, <OrganizationAddress1>, <OrganizationAddress2>, <OrganizationAddress3>, <OrganizationCity>, <OrganizationState>, <OrganizationInternationalState> and <OrganizationCountry> elements.  You can specify values in these elements that will be applied speicfically to the campaign you are creating.  They do not overwrite the default settings for the user.

 

The actual content of the campaign is described by <EmailContent>, <TextContent> and <StyleSheet> elements.  For HTML campaign, you need to specify <EmailContent> and <TextContent>  For XHTML, you need to specify <EmailContent>, <TextContent> and optionally <StyleSheet>.  Any values passed through these elements, in both HTML and XHTML, must be HTML-encoded in order for the API to work properly.  For example, '<' must be converted to '&lt;', etc.  Most programming languages offer ways to perform HTML-encoding so you must utilize such functionality to do this.  If you are creating an XHTML campaign, invalid XHTML in <EmailContent> will give you an error and the campaign will not be created.

 

To learn more about how to use HTML and XHTML in your custom code campaign, please consult the Advanced Editor User Guide.

 

<PermissionReminder> and <PermissionReminderText> specify whether you want to include a link for a confirmed opt-in in your email.  Please note that because the text is part of an email, you must HTML-encode any tags you choose to use in <PermissionReminderText>, such as <ConfirmOptIn> tag.

 

For more details on the XML specification of the request body, please refer to the Campaign Collection and Resource.