Make a POST call to the /emails endpoint to create a new email campaign. This method also creates new email campaign activities and associates them with the new email campaign.

Constant Contact supports different types of custom code emails using the format_type property. You can use the V3 API to create modern custom code emails (format_type 5) or legacy custom code emails (format_type 1). The V2 API created legacy custom code emails.

Feature Legacy Custom Code Modern Custom Code
Custom HTML Yes Yes
Inline CSS Yes Yes
CSS declarations in a <style> tag No Yes
Send the email to segments No Yes
Personalization tags (variables) Limited Full support including fallback text
Preview method processes personalization tags No Yes

For more information on creating HTML for modern custom code emails or using personalization tags, see Designing HTML for Modern Custom Code Emails.

Format Type Schema Differences

There are minor differences in the email campaign activity schema for the different email format types.

  • Format type 1 and 2 emails support a document_properties object. This object contains configuration information for the legacy email format types. The other format types do not.

  • Format type 3, 4, and 5 support the preheader property. The other format types do not.

  • Format type 3, 4, and 5 support adding an array of segment_ids to the email campaign. The other format types do not. Though you can add segments to an email, the V3 API does not currently provide methods to create or retrieve segments.

  • Format type 3, 4, and 5 support an address_optional property in the physical_address_in_footer object. The other format types do not.

  • Format type 1 and 5 (the custom code format types) support the html_content property. The other format types do not.

Authorization Requirements

User privileges: campaign:write

Authorization scopes: campaign_data

Create a New Email Campaign

Step 1: Create a Request Body for a Modern Custom Code Email

The request body must contain the name property and the email_campaign_activities array. The email_campaign_activities array contains the main content of your email campaign using the required properties format_type, from_name, from_email, reply_to_email, subject, and html_content.

name — A unique name that helps you identify the email campaign.

format_type — The email format you are using to create the email campaign activity. Use 5 to create a modern custom code email.

from_email — The email address that contacts use to identify who sent the email. You must use a confirmed Constant Contact account email address.

reply_to_email — The email address that contacts can use to reply to your email. You must use a confirmed Constant Contact account email address.

from_name — The email sender’s name that you display to contacts.

subject — The content displayed to contacts in the subject line of the email that describes the email to contacts.

html_content — The custom HTML you are including in your email. You must encode your HTML as a valid JSON string when you use it in the request body. For example, this bash script takes a HTML file named full_email and converts it to a valid JSON string:

full_email='cat full_email.html'
jq -aRs . <<< $full_email

Make sure that you include the tracking image tag, [[trackingImage]], in the <body> element of your HTML. The tracking image ensures that Constant Contact is able to accurately report on which contacts opened the email.

You can also include personalization tags in your HTML. These tags allow you to use contact, custom field, and Constant Contact account information as variables in your HTML. For more information, see Designing HTML for Modern Custom Code Emails.

Optionally, you can also include:

preheader — This property allows you to specify a message for your contact’s email clients to display following the email subject line.

physical_address_in_footer — By default, this method uses the saved physical address information for the Constant Contact user account when you send an email. If you include a physical_address_in_footer object in the email, Constant Contact will instead display the address information you provide in the email to contacts.

For more information about the schema, see the reference documentation for POST /emails.

Example JSON Request Body Schema

{
	"name": "December Newsletter for Cat Lovers",
	"email_campaign_activities": [{
		"format_type": 5,
		"from_email": "jdodge@example.com",
		"reply_to_email": "jdodge@example.com",
		"from_name": "Jake Dodge",
		"subject": "10 Holiday Specials for Cat Lovers",
		"html_content": "<html><body>[[trackingImage]]<a href=\"http://www.constantcontact.com\">Visit ConstantContact.com!</a></body></html>",
		"preheader": "Our Holiday Specials",
		"physical_address_in_footer": {
			"address_line1": "123 Maple Street",
			"address_line2": "Unit 1",
			"address_optional": "Near Boston Fire Station",
			"city": "Boston",
			"country_code": "US",
			"country_name": "United States",
			"organization_name": "Jake Dodge's Pet Supplies",
			"postal_code": "02451",
			"state_code": "MA"
		}
	}]
}

Step 2: Send the Request

Example POST /emails Request

This example POST /emails request creates a format_type 5 email (modern custom code). The example request also overrides the physical address settings in the Constant Contact user account by including a physical_address_in_footer object.

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n  \"name\": \"December Newsletter for Cat Lovers\",\n  \"email_campaign_activities\": [\n  \t{\n  \"format_type\": 5,\n  \"from_email\": \"jdodge@example.com\",\n  \"from_name\": \"Jake Dodge\",\n  \"reply_to_email\": \"jdodge@example.com\",\n  \"subject\": \"Our Holiday Specials\",\n  \"html_content\": \"<html><body>[[trackingImage]] <a href=\\\"http://www.constantcontact.com\\\">Visit ConstantContact.com!</a></body></html>\",\n  \"physical_address_in_footer\": {\n    \"address_line1\": \"123 Maple Street\",\n    \"address_line2\": \"Unit 1\",\n    \"address_line3\": \"string\",\n    \"address_optional\": \"Near Boston Fire Station\",\n    \"city\": \"Boston\",\n    \"country_code\": \"US\",\n    \"country_name\": \"United States\",\n    \"organization_name\": \"Jake Dodge Pet Supplies\",\n    \"postal_code\": \"02451\",\n    \"state_code\": \"MA\"\n  }\n}\n  ]\n}");
Request request = new Request.Builder()
  .url("https://api.cc.email/v3/emails")
  .post(body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "Bearer {access token}")
  .build();

Response response = client.newCall(request).execute();
curl -X POST \
  https://api.cc.email/v3/emails \
  -H 'Authorization: Bearer {access token}' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "December Newsletter for Cat Lovers",
  "email_campaign_activities": [
  {
  "format_type": 5,
  "from_email": "jdodge@example.com",
  "from_name": "Jake Dodge",
  "reply_to_email": "jdodge@example.com",
  "subject": "Our Holiday Specials",
  "html_content": "<html><body>[[trackingImage]] <a href=\"http://www.constantcontact.com\">Visit ConstantContact.com!</a></body></html>",
  "physical_address_in_footer": {
    "address_line1": "123 Maple Street",
    "address_line2": "Unit 1",
    "address_line3": "string",
    "address_optional": "Near Boston Fire Station",
    "city": "Boston",
    "country_code": "US",
    "country_name": "United States",
    "organization_name": "Jake Dodge Pet Supplies",
    "postal_code": "02451",
    "state_code": "MA"
  }
}
  ]
}'
<?php

$request = new HttpRequest();
$request->setUrl('https://api.cc.email/v3/emails');
$request->setMethod(HTTP_METH_POST);

$request->setHeaders(array(
  'Authorization' => 'Bearer {access token}',
  'Content-Type' => 'application/json'
));

$request->setBody('{
  "name": "December Newsletter for Cat Lovers",
  "email_campaign_activities": [
  	{
  "format_type": 5,
  "from_email": "jdodge@example.com",
  "from_name": "Jake Dodge",
  "reply_to_email": "jdodge@example.com",
  "subject": "Our Holiday Specials",
  "html_content": "<html><body>[[trackingImage]] <a href=\\"http://www.constantcontact.com\\">Visit ConstantContact.com!</a></body></html>",
  "physical_address_in_footer": {
    "address_line1": "123 Maple Street",
    "address_line2": "Unit 1",
    "address_line3": "string",
    "address_optional": "Near Boston Fire Station",
    "city": "Boston",
    "country_code": "US",
    "country_name": "United States",
    "organization_name": "Jake Dodge Pet Supplies",
    "postal_code": "02451",
    "state_code": "MA"
  }
}
  ]
}');

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

Modern custom code emails support more features than legacy custom code emails. Unless you currently rely on using dynamic links, Constant Contact recommends using the new custom code email format.

Step 1: Create a Request Body for a Legacy Custom Code Email

The request body must contain the name property and the email_campaign_activities array. The email_campaign_activities array contains the main content of your email campaign using the required properties format_type, from_name, from_email, reply_to_email, subject, and html_content.

name — A unique name that helps you identify the email campaign.

format_type — The email format you are using to create the email campaign activity. Use 5 to create a modern custom code email.

from_email — The email address that contacts use to identify who sent the email. You must use a confirmed Constant Contact account email address.

reply_to_email — The email address that contacts can use to reply to your email. You must use a confirmed Constant Contact account email address.

from_name — The email sender’s name that you display to contacts.

subject — The content displayed to contacts in the subject line of the email that describes the email to contacts.

html_content — The custom HTML you are including in your email. You must encode your HTML as a valid JSON string when you use it in the request body. For example, this shell script takes a HTML file named full_email and converts it to a valid JSON string:

full_email='cat full_email.html'
jq -aRs . <<< $full_email

Optionally, you can also include:

physical_address_in_footer — By default, this method uses the saved physical address information for the Constant Contact user account when you send an email. If you include a physical_address_in_footer object in the email, Constant Contact will instead display the address information you provide in the email to contacts.

document_properties — An object that contains optional configuration information for legacy emails. For more information about the valid properties you can use here, see the reference documentation for POST /emails.

Example JSON Request Body Schema

{
  "name": "December Newsletter for Dog Lovers",
  "email_campaign_activities": [
    {
      "format_type": 1,
      "from_name": "Jake Dodge",
      "from_email": "jdodge@constantcontact.com",
      "reply_to_email": "jdodge@constantconatct.com",
      "subject": "Informed Daily Digest",
      "html_content": "<html><body> <a href=\"http://www.constantcontact.com\">Visit ConstantContact.com!</a> </body></html>",
      "physical_address_in_footer": {
        "address_line1": "123 Maple Street",
        "address_line2": "Unit 1",
        "address_line3": "Example",
        "city": "Boston",
        "country_code": "US",
        "country_name": "United States",
        "organization_name": "Jake Dodge's Pancakes",
        "postal_code": "02451",
        "state_code": "MA",
      },
      "document_properties": {
        "style_content": ".white{color: #ffffff;}",
        "text_content": "<Text><Greetings/></Text>",
        "permission_reminder_enabled": "true",
        "permission_reminder": "Hi, just a reminder that you're receiving this email because you have expressed an interest in our company.",
        "view_as_webpage_enabled": "false",
        "view_as_webpage_text": "Having trouble viewing this email?",
        "view_as_webpage_link_name": "Click here to view this email as a web page",
        "greeting_salutation": "Hi,",
        "greeting_name_type": "F",
        "greeting_secondary": "Greetings!",
        "forward_email_link_enabled": "true",
        "forward_email_link_name": "Forward email",
        "subscribe_link_enabled": "false",
        "subscribe_link_name": "Subscribe to my email list!",
        "letter_format": "XHTML"
      }
    }
  ]
}

Step 2:Send the Request

Example POST /emails Request

This example POST /emails request creates a format_type 1 email (legacy custom code). The example request also overrides the physical address settings in the Constant Contact user account by including a physical_address_in_footer object.

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n  \"name\": \"December Newsletter for Dog Lovers\",\n  \"email_campaign_activities\": [\n    {\n      \"format_type\": 1,\n      \"from_name\": \"Jake Dodge\",\n      \"from_email\": \"jdodge@example.com\",\n      \"reply_to_email\": \"jdodge@example.com\",\n      \"subject\": \"Informed Daily Digest\",\n      \"html_content\": \"<html><body> <a href=\\\"http://www.constantcontact.com\\\">Visit ConstantContact.com!</a> </body></html>\",\n      \"physical_address_in_footer\": {\n        \"address_line1\": \"123 Maple Street\",\n        \"address_line2\": \"Unit 1\",\n        \"address_line3\": \"string\",\n        \"address_optional\": \"Near Boston Fire Station\",\n        \"city\": \"Boston\",\n        \"country_code\": \"US\",\n        \"country_name\": \"United States\",\n        \"organization_name\": \"Jake Dodge's Pancakes\",\n        \"postal_code\": \"02451\",\n        \"state_code\": \"MA\",\n        \"state_name\": \"string\",\n        \"state_non_us_name\": \"Victoria\"\n      },\n      \"document_properties\": {\n        \"style_content\": \".white{color: #ffffff;}\",\n        \"text_content\": \"<Text><Greetings/></Text>\",\n        \"permission_reminder_enabled\": \"true\",\n        \"permission_reminder\": \"Hi, just a reminder that you're receiving this email because you have expressed an interest in our company.\",\n        \"view_as_webpage_enabled\": \"false\",\n        \"view_as_webpage_text\": \"Having trouble viewing this email?\",\n        \"view_as_webpage_link_name\": \"Click here to view this email as a web page\",\n        \"greeting_salutation\": \"Hi,\",\n        \"greeting_name_type\": \"F\",\n        \"greeting_secondary\": \"Greetings!\",\n        \"forward_email_link_enabled\": \"true\",\n        \"forward_email_link_name\": \"Forward email\",\n        \"subscribe_link_enabled\": \"false\",\n        \"subscribe_link_name\": \"Subscribe to my email list!\",\n        \"letter_format\": \"XHTML\"\n      }\n    }\n  ]\n}");
Request request = new Request.Builder()
  .url("https://api.cc.email/v3/emails")
  .post(body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "Bearer {access_token}")
  .build();

Response response = client.newCall(request).execute();
curl -X POST \
  https://api.cc.email/v3/emails \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "December Newsletter for Dog Lovers",
  "email_campaign_activities": [
    {
      "format_type": 1,
      "from_name": "Jake Dodge",
      "from_email": "jdodge@example.com",
      "reply_to_email": "jdodge@example.com",
      "subject": "Informed Daily Digest",
      "html_content": "<html><body> <a href=\"http://www.constantcontact.com\">Visit ConstantContact.com!</a> </body></html>",
      "physical_address_in_footer": {
        "address_line1": "123 Maple Street",
        "address_line2": "Unit 1",
        "address_line3": "string",
        "address_optional": "Near Boston Fire Station",
        "city": "Boston",
        "country_code": "US",
        "country_name": "United States",
        "organization_name": "Jake Dodge'\''s Pancakes",
        "postal_code": "02451",
        "state_code": "MA",
        "state_name": "string",
        "state_non_us_name": "Victoria"
      },
      "document_properties": {
        "style_content": ".white{color: #ffffff;}",
        "text_content": "<Text><Greetings/></Text>",
        "permission_reminder_enabled": "true",
        "permission_reminder": "Hi, just a reminder that you'\''re receiving this email because you have expressed an interest in our company.",
        "view_as_webpage_enabled": "false",
        "view_as_webpage_text": "Having trouble viewing this email?",
        "view_as_webpage_link_name": "Click here to view this email as a web page",
        "greeting_salutation": "Hi,",
        "greeting_name_type": "F",
        "greeting_secondary": "Greetings!",
        "forward_email_link_enabled": "true",
        "forward_email_link_name": "Forward email",
        "subscribe_link_enabled": "false",
        "subscribe_link_name": "Subscribe to my email list!",
        "letter_format": "XHTML"
      }
    }
  ]
}'
<?php

$request = new HttpRequest();
$request->setUrl('https://api.cc.email/v3/emails');
$request->setMethod(HTTP_METH_POST);

$request->setHeaders(array(
  'Authorization' => 'Bearer {access_token}',
  'Content-Type' => 'application/json'
));

$request->setBody('{
  "name": "December Newsletter for Dog Lovers",
  "email_campaign_activities": [
    {
      "format_type": 1,
      "from_name": "Jake Dodge",
      "from_email": "jdodge@example.com",
      "reply_to_email": "jdodge@example.com",
      "subject": "Informed Daily Digest",
      "html_content": "<html><body> <a href=\\"http://www.constantcontact.com\\">Visit ConstantContact.com!</a> </body></html>",
      "physical_address_in_footer": {
        "address_line1": "123 Maple Street",
        "address_line2": "Unit 1",
        "address_line3": "string",
        "address_optional": "Near Boston Fire Station",
        "city": "Boston",
        "country_code": "US",
        "country_name": "United States",
        "organization_name": "Jake Dodge's Pancakes",
        "postal_code": "02451",
        "state_code": "MA",
        "state_name": "string",
        "state_non_us_name": "Victoria"
      },
      "document_properties": {
        "style_content": ".white{color: #ffffff;}",
        "text_content": "<Text><Greetings/></Text>",
        "permission_reminder_enabled": "true",
        "permission_reminder": "Hi, just a reminder that you're receiving this email because you have expressed an interest in our company.",
        "view_as_webpage_enabled": "false",
        "view_as_webpage_text": "Having trouble viewing this email?",
        "view_as_webpage_link_name": "Click here to view this email as a web page",
        "greeting_salutation": "Hi,",
        "greeting_name_type": "F",
        "greeting_secondary": "Greetings!",
        "forward_email_link_enabled": "true",
        "forward_email_link_name": "Forward email",
        "subscribe_link_enabled": "false",
        "subscribe_link_name": "Subscribe to my email list!",
        "letter_format": "XHTML"
      }
    }
  ]
}');

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

Example Response Body

{
    "type": "CUSTOM_CODE_EMAIL",
    "name": "December Newsletter for Cat Lovers",
    "campaign_id": "a4cebf51-b837-48bc-8f2f-60de0fc6af46",
    "current_status": "Draft",
    "updated_at": "2019-12-11T18:13:24.168Z",
    "created_at": "2019-12-11T18:13:24.168Z",
    "campaign_activities": [
        {
            "role": "primary_email",
            "campaign_activity_id": "1cac1868-6972-4fc9-8110-3dafe4d11309"
        },
        {
            "role": "permalink",
            "campaign_activity_id": "2c23c3e6-5540-4106-917e-75dff3973e18"
        }
    ]
}

After you create an email campaign, use the PUT /emails/activities/{campaign_activity_id} method to update the email campaign activity with the contacts that you want to receive the email.

You currently cannot add contacts when you initially use the POST /emails method to create the campaign. For more information on updating an email campaign activity, see the Update an Email Campaign Activity topic.

If you want to try out this API request, use the API reference documentation to send a test request. Try it!