Here we provide you with DO's and DON'Ts on using the Contacts endpoints so that you can build a great integration that provides your users a great experience.
The following best practices are intended to give your users the best experience possible, and make your integration as efficient as possible.
This process uses 2 API calls to add a contact to Constant Contact, one to determine if it already exists, and one to add it. It is fine to use this process if you are adding a fairly small number of contacts. Keep in mind that API keys have a limit on the number of API calls that can be made per day, and per second. See API Keys for info. If you are adding a large number of contacts, it's best to use the batch import methods described below.
The action_by query parameter tells the system who initiated an action, the contact or the account owner. Whenever a contact subscribes to a contact list by entering their email address and clicking Subscribe me,
DO Use this workflow to create a new contact and prevent receiving a 409 response for trying to create a contact that already exists.
action_by=ACTION_BY_VISITOR. See Contact Status for more information.
A new contact is sent an auto-responder welcome email when the POST call to the contacts collection includes the query parameter
action_by=ACTION_BY_VISITOR. If the contact is added with
action_by=ACTION_BY_OWNER, a welcome message is not sent. Additionally, if Confirmed Opt-in is enabled for the account, any contacts added with
action_by=ACTION_BY_VISITOR must confirm their subscription. The Confirmed Opt-in setting is available in the product UI, and not via the API.
|How contact subscribed||action_by=||Welcome message sent?||Confirm Opt-in =||Contact must confirm subscription?|
|Contact signs up using Join My Mail List||ACTION_BY_VISITOR||yes||No||No|
|Account owner adds contact to account||ACTION_BY_OWNER||no||No||No|
This process uses 2 API calls to update a contact, one to get the current contact properties, and one to put the updated properties. It is fine to use this process if you are updating a fairly small number of contacts. Keep in mind that API keys have limits on the number of calls that can be made per day, and per second. See API Keys for info. If you are updating a large number of contacts, it's best to use the batch import methods.
HOW Make a PUT call to the Individual Contact endpoint.
DO Make a GET call to retrieve all the properties for a contact prior to updating it. All updates (PUTs) are full replacements of the contact properties. That means you need to include the original content that is not changing, plus the new and changed content in the PUT. Otherwise, all properties not specified in the PUT will be overwritten with a null set.
If you are have a large number of contacts that you need to compare and update, see Updating many contacts efficiently.
The bulk activity endpoints allow you to add or update up to 20,000 contacts by making 1 or 2 API calls.
The process described here imports all contacts in your local application or database to Constant Contact, regardless of whether they are:
This single-step process does not require you to compare contact data in Constant Contact with your local data. However, if you are making updates to an existing contact list, it assumes that your local data is being synced with Constant Contact data on a regular basis. This is important because this method will overwrite any preference changes made by a contact in the Constant Contact data, such as list subscriptions, that are not recorded in the local data. For example, if a contact removed themselves for the "Weekly Specials" campaign sent to list_id=2, and the bulk import/update call specifies adding all the contacts to lists 2, 3, and 4, that subscriber will now be resubscribed to list_id=2. This is likely to raise the ire of at least some of these contacts.
DON'T update an existing list without having synced the local data with Constant Contact.
Do This is the best way to populate a new list.
When executed, all contacts are imported into Constant Contact:
This process updates only new contacts or existing contacts whose information has changed using only 2 API calls, one to export the contacts from Constant Contact, and one to import them back in.
DON'T Perform brute force list updates.
A brute force update occurs when an integration first removes all contacts from an existing list using the Clear Contacts bulk activity endpoint. Then, it immediatlely repopulates the list using the Import Contacts (JSON or Multipart) bulk activity endpoint with the contact data stored on in the local CRM or other contact/customer manangement application. Wiping out a list and then adding local contact data that has not been synced with Constant Contact to the now empty list will ignore any preference changes that a contact made to their profile. You risk adding contacts to a list that they have already unsubscribed from, something that should be avoided at all times.
This table summarizes the possible status values for a contact.
|Contact Status||Description||Customer charged for contact?|
|UNCONFIRMED||The contact has been added by the Constant Contact account; the account cannot send the contact email messages until they contact confirm their subscription, at which time the status changes to ACTIVE.||No|
|ACTIVE||The contact subscribed them self to an email list, or they confirmed their subscription after being added by the account. They can be sent email campaigns.||Yes|
|OPTOUT||The contact has either unsubscribed themselves, or the account owner has DELETED the contact, placing them on the Unsubscribed list; the Contant Contact user cannot add them to any of their contact lists. See Opting Contacts Back in to learn how a contact can change their status from OPTOUT to ACTIVE.||No|
The contact has been removed by the account owner, and they can be added to a list at any time.NOTE: Using the Bulk Remove method will NOT change a contact to Removed status. You can only change a contact to Removed status by using the individual contact method.
|NON_SUBSCRIBER||The contact has registered for an account's event, but has not subscribed to any email lists.||No|
Deleting a contact is very different from removing a contact from all lists.
A contact that has been removed from all contact lists by the account owner has a
status=REMOVED. To remove a contact from all lists, update the contact with an empty lists array. The contact can be added back to a list at anytime.
Deleting a contact using the DELETE Contact method changes their status to OPTOUT, placing them on the Unsubscribed list; the account owner cannot add them to any of their contact lists and cannot contact them. See Opting Contacts Back in to learn how a contact can change their status from OPTOUT to ACTIVE.
All contacts with
status=OPTOUT have unsubscribed from all contact lists, and are on the Unsubscribed list. Contacts on the Unsubscribed list cannot be subscribed to any list by a Constant Contact account owner (
action_by=ACTION_BY_OWNER), EVEN IF the account owner unsubscribed the contact (accidentally or purposefully). The contact must re-subscribe themselves to a contact list in order to be removed from the Unsubscribed list.
When an existing unsubscribed contact subscribes to a contact list, the PUT call that updates their record must include the query parameter
action_by=ACTION_BY_VISITOR. Also, they must be added to a contact list when adding them to the contact collection. The
action_by parameter defines who initiated the action of adding the contact.
It is a violation of US and Canadian anti-spam laws, as well as a serious violation of the Constant Contact Terms of Service to use the Opt-in features of the API to opt a contact back in without his or her own action and consent.
modified_since query parameter to streamline contact syncing betweeen Constant Contact and other applications. The modified_since parameter allows you to sync only the contacts that have been modified since the last contact sync activity by specifying the date and time of the last sync. modified_since is updated to reflect when any of the following contact properties are modified in the API or the product UI:
You can use the contacts tracking API to sync contacts based on their activities, such as opting out, unsubscribing, or clicking links in email campaigns using the created_since query parameter. For example, you may want to sync all contacts who have unsubscribed from a newsletter since the beginning of the quarter.
DO Because we know our customers rate this feature highly, we stongly encourage all Constant Contact integrations allow users to upload contacts to a contact list of the user's choosing. For an even better user experience, allow users to create a new contact list to add contacts to. It may seem like a small thing, but Constant Contact users depend on being able to create lists to segment their contacts.