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 custom code emails (format_type 5).

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

For more information on creating HTML for custom code emails or using personalization tags, see Designing HTML for 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 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 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 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 (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;
}

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"
        }
    ]
}

If you use a legacy format_type when creating your email campaign, Constant Contact automatically converts it to the newer custom code format_type.

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!