WhatCounts FAQs

The Get Subscriptions command allows you to get all Subscriber and Custom Data and List Subscriptions for a Subscriberspecified bythe Customer Key in Realms where the option is enabled.

GET/subscribers/[customerKey]/subscriptions

https://[siteurl]/rest/subscribers/[customerKey]/subscriptions

Request Body Parameters

The Get Subscriptions by Customer Keycommand requires only the URI call with the Customer Keyand Subscriptions parameter.No additional fields are required in the JSON.

Request Body Example

Using Get Subscriptions:

curl --request GET \

--url 'https://mail.mydomain.com/rest/subscribers/ck10/subscriptions' \

--header 'authorization: Basic bXlBY2NvdW50Onh5enB3ZDEyMw==' \

--header 'accept: application/vnd.whatcounts-v1+json' \

--header 'content-type: application/json' \

--include

Response Body

The response returns all API available Fieldsin JSON format for the specified Subscriber.

Based on the example above, the response returns:

HTTP/1.1 200 OK

Server: serverName

Content-Type: application/json

Link: <https://mail.mydomain.com/rest/subscribers/ck10/subscriptions>;

Date: Fri, 17 Jun 2016 12:54:44 GMT

{

"subscriberId": 10

"realmId": 1561

"email": "[email protected]"

"firstName": "Jon"

"lastName": "Doe"

"company": "My Company"

"address1": "123 Some Street North"

"address2": "Suite 500"

"city": "My City"

"state": "WA"

"zip": "98000"

"country": "United States"

"phone": "(206) 555 1212"

"fax": ""

"createdDate": "May 21, 2012 9:14:16 AM"

"updatedDate": "Nov 2, 2015 10:31:27 AM"

"customerKey": "ck10"

"ipAddress": ""

"md5Encryption": "C8ADED17D5F088E8262BF31ED933B7D4"

"sha1Encryption": "356B1860247728C81486A35062688F302D96C2D1"

"subscriptions":

{

"subscriptionId": 31263419

"subscriberId": 10

"listId": 11

"formatId": 2

"createdDate": "Jul 13, 2015 3:28:59 PM"

"listName": "Monthly Mailer"

"skip": 3

"max": 0

}

{

"subscriptionId": 31263417

"subscriberId": 10

"listId": 5

"formatId": 1

"createdDate": "Jul 13, 2015 3:28:59 PM"

"listName": "myList"

"skip": 2

"max": 0

}

{

"subscriptionId": 31263418

"subscriberId": 10

"listId": 10

"formatId": 99

"createdDate": "Jun 13, 2015 9:28:59 PM"

"listName": "list Subscriptions"

"skip": 1

"max": 0

}

"customData": {

"text": "text"

"unicode": "unicode text"

"large": "big"

"number": 12

"float": 12.12

"date": "2016-07-04"

},

"skip": 1

"max": 0

}

Error Response

Error Response Codes include both Client Errors (4xx) and Server Errors (5xx). Descriptions of each can be found in Response Codes.

For example, if thespecified Subscriberdoes not exist, the error would appear as:

{

"error": "Unable to find resource with customerKey = ck10"

"status": "Not Found"

"statusCode": 404

}

The Get Subscriptions command allows you to get all Subscriber and Custom Data and List Subscriptions for a Subscriberspecified bythe Subscriber ID.

GET/subscribers/[subscriberId]/subscriptions

https://[siteurl]/rest/subscribers/[subscriberId]/subscriptions

Request Body Parameters

The Get Subscriptions by Subscriber ID command requires only the URI call with the SubscriberID and Subscriptions parameter.No additional fields are required in the JSON.

Request Body Example

Using Get Subscriptions:

curl --request GET \

--url 'https://mail.mydomain.com/rest/subscribers/10/subscriptions' \

--header 'authorization: Basic bXlBY2NvdW50Onh5enB3ZDEyMw==' \

--header 'accept: application/vnd.whatcounts-v1+json' \

--header 'content-type: application/json' \

--include

Response Body

The response returns all API available Fieldsin JSON format for the specified Subscriber.

Based on the example above, the response returns:

HTTP/1.1 200 OK

Server: serverName

Content-Type: application/json

Link: <https://mail.mydomain.com/rest/subscribers/10/subscriptions>;

Date: Fri, 17 Jun 2016 12:54:44 GMT

{

"subscriberId": 10

"realmId": 1561

"email": "[email protected]"

"firstName": "Jon"

"lastName": "Doe"

"company": "My Company"

"address1": "123 Some Street North"

"address2": "Suite 500"

"city": "My City"

"state": "WA"

"zip": "98000"

"country": "United States"

"phone": "(206) 555 1212"

"fax": ""

"createdDate": "May 21, 2012 9:14:16 AM"

"updatedDate": "Nov 2, 2015 10:31:27 AM"

"ipAddress": ""

"md5Encryption": "C8ADED17D5F088E8262BF31ED933B7D4"

"sha1Encryption": "356B1860247728C81486A35062688F302D96C2D1"

"subscriptions":

{

"subscriptionId": 31263419

"subscriberId": 10

"listId": 11

"formatId": 2

"createdDate": "Jul 13, 2016 3:28:59 PM"

"listName": "Monthly Mailer"

"skip": 3

"max": 0

}

{

"subscriptionId": 31263417

"subscriberId": 10

"listId": 5

"formatId": 1

"createdDate": "Jul 13, 2016 3:28:59 PM"

"listName": "myList"

"skip": 2

"max": 0

}

{

"subscriptionId": 31263418

"subscriberId": 10

"listId": 10

"formatId": 99

"createdDate": "Jun 13, 2015 9:28:59 PM"

"listName": "list Subscriptions"

"skip": 1

"max": 0

}

"customData": {

"text": "text"

"unicode": "unicode text"

"large": "big"

"number": 12

"float": 12.12

"date": "2016-07-04"

},

"skip": 1

"max": 0

}

Error Response

Error Response Codes include both Client Errors (4xx) and Server Errors (5xx). Descriptions of each can be found in Response Codes.

For example, if thespecified Subscriberdoes not exist, the error would appear as:

{

"error": "Unable to find resource with id = 10"

"status": "Not Found"

"statusCode": 404

}

Overview

The Subscription Form allows anyone to submit at least an email address to subscribe to a list.

To Create a Subscription Form

Go to SUBSCRIBERS > SUBSCRIPTION FORM WIZARD.

Select a List.

From Generate select 'Subscribe Form'.

Select the Default Format, which will determine the prefered email format: Multipart MIME, HTML, Plain Text.

Select 'Show checkboxes for format choices' to allow your subscribers to choose a preferred email format.

Select 'Show checkbox for RSS Signup' to allow your subscribers to subscribe to the RSS feed for your List. (* Removed in v11.16.0 )

Enter a Goto URL for the landing page. If no landing page is defined, the form will use the Landing Page defined in your List properties. If no Landing Page is defined, the subscriber will see a default platform welcome page.

Enter an Error Landing Page. If no Landing Page is defined, the subscriber will see a default platform error page.

Click NEXT.

Select Subscriber Data fields and/or Custom Data fields to include in the form. Each selected field will appear in the form with the field name as the label for a text box. Email is required by default and cannot be deselected.

Click NEXT.

Select the form code and paste into a text editor to customize the form further.

Test the form, then place the form code iinto your website.

Example

The following is an example of how the form code will appear, where [slid] is the special list id, [gotoURL] is the success Landing Page, and [errorURL] is the Error Landing Page.

NOTE: If you are on a Broadcaster, make sure you replace the form "action" value with the one appropriate for your Broadcaster.

<form action="http://whatcounts.com/bin/listctrl" method="POST">

<input type=hidden name="slid" value="[slid]" />

<input type=hidden name="cmd" value="subscribe" />

<input type=hidden name="goto" value="[gotoURL]" />

<input type="hidden" name="errors_to" value="" />

<table>

<tr>

<td style="text-align:right;">Email:</td>

<td><input type="text" id="email" name="email" size="25" /></td>

</tr>

<tr>

<td style="text-align:right;">First:</td>

<td><input type="text" id="first" name="first" size="25" /></td>

</tr>

<tr>

<td style="text-align:right;">Last:</td>

<td><input type="text" id="last" name="last" size="25" /></td>

</tr>

<tr>

<td style="text-align:right;">Zip:</td>

<td><input type="text" id="zip" name="zip" size="25" /></td>

</tr>

<tr>

<td style="text-align:right;">Birthdate:</td>

<td><input type="text" id="custom_birthdate" name="custom_birthdate" size="25" /></td>

</tr>

<tr>

<td> </td>

<td>

<input type="hidden" id="format_mime" name="format" value="mime" />

<input type="button" value="Cancel" />

<input type="submit" value="Subscribe" />

</td>

</tr>

</table>

</form>

Testing the Form

Once you have created a form, test it to ensure it is functioning as expected. To test your subscription form:

Save the form as an .html file.

Open the .html file in your browser.

Fill the form fields with a test Email address and subscriber information, then submit the form. Verify the expected landing page is displayed.

If you have Subscription Confirmation required in your List properties, you will receive an email with a link to confirm your subscription. Click the link to subscribe.

Login to your realm.

Go to SUBSCRIBERS > SEARCH FOR SUBSCRIBER.

Enter the Email address submitted above, then click SEARCH.

Double click the subscriber record to view the details.

Validate the Subscriber and Custom Data, and verify the subscription was created in the Subscription tab set to the expected format.

The Add SMS Subscriber to Sender Code command allows you to subscribe an existing SMS subscriber to an SMS Sender Code.

POST /sms/addSubscriberToSenderCode

https://[siteurl]/rest/sms/addSubscriberToSenderCode/[email]/[phone]/[senderCode]?querystring

The following queries are supported:

groupName=[string]

first=[string]

customerKey=[string]

Request Body Parameters

TheAdd SMS Subscriber to Sender Code commandrequires the URI call with the Subscriber Email, Phone and SMS Sender Code.Optional Filter includes the Group Name and First name parameters. Customer Key isrequired in Realms with Customer Key enabled.

The query strings 'groupName','first', and 'customerKey' are case sensitive and must be defined as in the example above. A Group Name must be defined in order to save. If the query string is incorrect or missing, it is ignored and the command creates a message with no label.

Request Body Example

Using Add SMS Subscriber to Sender Code with all arguments, line breaks in JSON for readability:

curl --request POST \

--url 'https://mail.mydomain.com/rest/sms/addPhoneToSenderCode/[email protected]/2065559696?groupName=weekly&first=Jon&customerKey=jDoe3214' \

--header 'authorization: Basic bXlBY2NvdW50Onh5enB3ZDEyMw==' \

--header 'content-type: application/json' \

--header 'accept: application/vnd.whatcounts-v1+json' \

--include

Response Body

The response returns JSON or an HTTPstatus code. Based on the first example above, the response returns:

HTTP/1.1 200 OK

Server: serverName

Content-Type: application/json

Content-Length: 456

Date: Fri, 16 Mar 2018 09:10:50 GMT

{

"success": true,

"createDate": "Jan 27, 2020 9:12:31 AM",

"updatedDate": "Jan 27, 2020 9:12:31 AM",

"realmId": 1,

"smsSubscriberId": 5,

"id": 7,

"groupName": "smsGroup",

"phone": "15558999520"

}

Error Response

Error Response Codes include both Client Errors (4xx) and Server Errors (5xx). Descriptions of each can be found in Response Codes. An error will occur if Message Name or Text is blank, or a Message with the same Name already exists.

For example, if a Subscription already exists for the Subscriber, the error would appear as:

{

"error": "Unable to create subscriber record. A subscriber with this phone number already exists."

"status": "Internal Server Error"

"statusCode": 500

}

Feature added in v12.16.0

The Send SMS Message to Phone command allows you to send any SMS message text to a specified Phone number. An SMS Subscription or Subscriber is not required, and the command does not validate if the Phone is subscribed. The command provides the option to send to a Phone number directly without predefined message content. The command does honor all SMS opt outs with no option to override the opt out.

POST /sms/sendMessageToPhone

https://[siteurl]/rest/sms/sendMessageToPhone/[messageText]/[phone]/[senderCode]

Request Body Parameters

The Send SMS Message to Phone commandrequires the URI call with the one off Message Text, Phone, and Sender Code.

Request Body Example

Using Send SMS Message to Phone with all arguments, line breaks in JSON for readability:

curl --request POST \

--url 'https://mail.mydomain.com/rest/sms/sendMessageToPhone/One+time+message+for+you./2065559696/2065551212' \

--header 'authorization: Basic bXlBY2NvdW50Onh5enB3ZDEyMw==' \

--header 'content-type: application/json' \

--header 'accept: application/vnd.whatcounts-v1+json' \

--include

Response Body

The response returns JSON or an HTTPstatus code. Based on the first example above, the response returns:

HTTP/1.1 200 OK

Server: serverName

Content-Type: application/json

Content-Length: 456

Date: Fri, 16 Mar 2018 09:10:50 GMT

{

[

{

"success": true,

"createDate": "Jan 27, 2020 1:13:54 PM",

"updatedDate": "Jan 27, 2020 1:13:54 PM",

"partSent": 1,

"realmId": 1,

"smsSenderId": 5,

"totalParts": 1,

"messageId": "13000000AB005CC6",

"phone": "15558999520",

"status": "0"

}

]

}

Error Response

Error Response Codes include both Client Errors (4xx) and Server Errors (5xx). Descriptions of each can be found in Response Codes. An error will occur if Message Name or Text is blank, or a Message with the same Name already exists.

For example, if the Sender Code does not exist, the error would appear as:

{

"error": "Error getting sender with senderCode 1 realmID: 10"

"status": "Internal Server Error"

"statusCode": 500

}

Feature added in v12.16.0

The Create SMS Message command allows you to define message content to send via SMS. The command requires the following arguments: Command, Realm, Password, Message Name, and Message Text.

api_web?r=myrealm&p=mypass&c=createsmsmessage&message_name=My+SMS+Message&message_text=SMS+message+text

The command is ‘createsmsmessage', the realm is ‘myrealm’ and the password is ‘mypass’. The message named ‘My SMS Message’ contains the message ‘SMS Message Text’ .

Example

Using createsmsmessagewith all commands and arguments (please note the command is wrapped for display purposes only):

api_web?r=myrealm&p=mypass&c=createsmsmessage&message_name=Welcome+Back&message_text=Welcome+back+to+our+list!&label=welcome

Successful results return, where ‘6’ is the ID of the new message:

SUCCESS: 6

Results

The Create SMS Message command outputs either a SUCCESS or FAILURE message.

Success

The command success message returns the SUCCESS messagefollowed by the new message ID. The result format is:

SUCCESS: [message_id]

Failure

Thecommand will fail for several reasons, including if a message with the same name already exists, name is missing, label does not exist, message name includes special characters, or the message is too long. The result format is:

FAILURE: [Reason]

Errors include:

FAILURE: Error label name not found (The message will still be created, but with no label)

FAILURE: Message text cannot be more than 160 characters long

FAILURE: Message text cannot be empty.

Arguments

The command supports the following arguments:

Name

Req?

Description

Argument

Command

Yes

Defines the command to use.

cmd=createsmsmessage

c=createsmsmessage

Realm

Yes

Name of the realm to run the command. This is required, and the command will fail if the realm and password do not match.

realm=[realm_name]

r=[realm_name]

Password

Yes

Authentication code for API access. This is required, and the command will fail if the realm and password do not match.

pwd=[password]

p=[password]

Message Name

Yes

Name of the SMS message to create. To include spaces, use + or \%20 to avoid possible issues with spaces in a URL.

message_name=[msg_name]

Message Text

Yes

The message to send, limited to 160 characters.To include spaces, use + or \%20 to avoid possible issues with spaces in a URL.

message_text=[text]

Labels

Comma separated list of identifiers of custom keywordstoidentify and reportitems that have a similar use or purpose. The label(s) must be defined for the Realm and associated to the SMS product in order to save.

label=[label_id(s)]

The SMS Save or Subscribe to SMS command allows you to add a Subscriber to send SMS messages. The Subscribe to SMS command requires the following arguments: Command, Data with Country, SMS Subscriber Phone, and SMS Sender Code in the following order.

cmd=smssave&data=country,phone,sender^US,5555091000,12016270164

The command is ‘smssave', and a subscription for the US phone number '5555091000' will be added to SMS Sender Code '12016270164' currently defined in the realm.

You can add one or many subscribers with the same subscribe command. To add multiple subscribers, include additional subscribers separated by the carat (^) character. Each additional subscriber must have the same number of data fields defined.

The SMS Save command expects as least three fields in the Data argument: the SMS sender, SMS Subscriber phone number and country code are always required to create an SMS subscription record. A normal Subscriber record is not necessary. The optional SMS Group ID can also be included in a command for SMS Subscribers that do not correspond to an email Subscriber.

cmd=smssave&data=country,phone,sender,sms_group_id^US,5555091000,12016270164,21

The Phone number must be unique to a single SMS Subscriber. Attempting to add an SMS Subscription using the same Phone number for multiple subscribers will result in a failure. The SMS subscription will also fail when attempting to add with a Subscriber email that does not exist. If multiple subscribers have the same email address, you must include the first name with the email address, or use the subscriber ID, in order to associate the SMS subscription to the correct subscriber.

The Data fields supported include:

Name

Field

Description

SMS Sender

sender

Sender Code representing the message sender. A Sender Code is either a short code or number. It represents the 'from' field when deploying an SMS. The message recipient will see this sender on their mobile device when a message is received. The Sender Code must be define in the SMS UI prior to adding SMS Subscribers.

Subscriber Phone

phone

Numeric phone number for the Subscriber. Do not include special characters (such as parenthesis or dash). This SMS Phone number does not need to match that of the Phone number stored for the Subscriber Data Fields.

Country

country

Two letter country code for the Subscriber phone carrier. Only US is supported at this time.

Subscriber ID

subscriber_id

Subscriber ID of the Subscriber to subscribe to SMS. Can be used in place of Email+First or Customer Key.

First Name

first

First name of the Subscriber to subscribe to SMS. Must be used with Email.

Email

email

Email address of the Subscriber to subscribe to SMS. Subscriber must already exist as a regular Email subscriber, even if not subscribed to any List.

Customer Key

customer_key

Customer Key of the Subscriber to subscribe.Subscriber must already exist as a regular Email subscriber, even if not subscribed to any List.

SMS Group

sms_group_id

Group to associate SMS Subscription for sending batch messages. Group is optional.

Resubscribe

When an SMS Subscriber opts out of future messages by sending a STOP request, an Opt Out record is created which prevents both future subscriptions and sending future messages. To override an opt out you must use theforce_subscribeargument in the header of your FTP file. This should only be used in very specific cases in which you have verified the subscriber's desire to opt in to your list. To learn more about Force Subscribe, see the FTP API Conventions.

Example

Using all commands and arguments (please note the command is wrapped for display purposes only, and the field order is required):

cmd=smssave&data=country,phone,subscriber_id,sender,first,email,sms_group_id^US,5555555008,555,120162701645,Jane,[email protected],12

The normal Subscriber, ‘[email protected]’, will be subscribed to SMS Sender ‘18005559999’ in the SMS Group with ID '12'.

You can also identify the Subscriber using email and first name or subscriber ID only.

cmd=smssave&data=country,phone,subscriber_id,sender,first,email,sms_group_id^US,5555555008,,120162701645,Jane,[email protected],12

cmd=smssave&data=country,phone,subscriber_id,sender,first,email,sms_group_id^US,5555555008,555,120162701645,,12

Customer Key Example

Some systems have the ability to define a unique Customer Key per subscriber. If your realm has Customer Key enabled, then you can use the customer_key in the data argument to identify the Subscriber. For example:

cmd=smssave&data=country,phone,subscriber_id,sender,first,email,customer_key,sms_group_id^US,5555555008,,120162701645,,,555Jane,12

You can also identify the Subscriber using email and first name or subscriber ID.

cmd=smssave&data=country,phone,subscriber_id,sender,first,email,customer_key,sms_group_id^US,5555555008,,120162701645,Jane,[email protected],,12

cmd=smssave&data=country,phone,subscriber_id,sender,first,email,customer_key,sms_group_id^US,5555555008,555,120162701645,,,12

Errors

The SMS Save command will fail if the SMS feature is not enabled for the realm. It will also fail if an invalid SMS sender code, subscriber, or SMS group is specified or if an optout is encountered for the phone number. The command will also fail if the Subscriber does not exist or an SMS subscription already exists for the specified phone number. It does not validate that the Subscribers Phone matches the SMS Phone. Several example errors include:

SMS Sender could not be found for sender code

An SMS Subscription already exists

Country, Sender Code, Phone cannot be empty

Phone should only contain numeric digits

SMS Group could not be found with ID

Country Code is not supported (only US is supported at this time)

Email Subscriber could not be retrieved with the provided information.

Array index out of range (number of fields defined does not match number of data fields in command)

Arguments

The SMS Save command supports the following arguments:

Name

Req?

Description

Argument

Command

Yes

Defines the command to use.

cmd=smssave

Data

Yes

Subscriber related data. Phone, Country, and Sender are always required, and additional fields are optional.

data=[fields]

The Create Subscription and Send to Subscriber in List command allows you to subscribe an email address to a list and send a single transactional style message to the subscriber.

These messages are individually created and sent but can be tracked together as a sticky campaign to collect data as a single campaign. To group your data into a single campaign, use a List with Sticky Campaigns enabled.

This command does not support the same features as the HTTP API, FTP API, or WebServices API Send commands, including the ability to define Google Analytics strings, Account Profile, Subscriber Data for personalization, or Campaign Name.If your Template includes Subscriber or Custom Data, you must create the subscriber first and import the data you wish to fill the Template before using this command.

POST /lists

https://[siteurl]/rest/lists/subandsend/[listId]/[templateId]?querystring

The following queries are supported:

format=[1,2,99],where 1=plain text, 2=html, and 99=MIME

duplicates=[0,1], where 0=Do not search for duplicate subscriber, default; 1=Use first matched subscriber

campaignName=[string],

To track one-off message events, such as opens and click-throughs, define a campaign name. The Campaign Name can be no longer than 100 characters. A single list can have multiple campaigns by defining a different Campaign Name in a command.

snapshot=[0,1],

If Email Snapshot is enabled for a realm, the snapshot flag providesthe ability to save and store HTML and PNG screenshots of emails. To store a snapshot, set this argument to '1'.

Request Body Parameters

The Create Subscription and Send to Subscriber in List commandrequires the URI call with the List ID and Template ID.Optional Filters include Format, Duplicates, Campaign Name, and Email Snapshot parameters.

The query strings are case sensitive and must be defined as in the example above. If the query string is incorrect or missing, it is ignored and the command creates a Plain Text message without duplication, sending to the first subscriber found to match the posted JSON.

The command also requires the following in the Posted JSON:

Email:"email": [email], Required in non-Customer Key enabled realm

First Name:"firstName": [firstName], Optional

To send to a Subscriber in a Customer Key enabled Realm, you must also include the Customer Key in the JSON:

Customer Key:"customerKey": [customerKey]

Request Body Example

UsingCreate Subscription and Send to Subscriber in List with all arguments, line breaks in JSON for readability:

curl --request POST \

--url 'https://mail.mydomain.com/rest/lists/subandsend/13/42?format=99&duplicates=0&campaignName=myCampaign&snapshot=1' \

--header 'authorization: Basic bXlBY2NvdW50Onh5enB3ZDEyMw==' \

--header 'content-type: application/json' \

--header 'accept: application/vnd.whatcounts-v1+json' \

--data '{

"subscriberId": 716094,

"email": "[email protected]"

}' \

--include

Using Create Subscription and Send to Subscriber in List in a Customer Key enabled Realm, line breaks in JSON for readability:

curl --request POST \

--url 'https://mail.mydomain.com/rest/lists/13/2?format=99&duplicates=0&campaignName=myCampaign&snapshot=1' \

--header 'authorization: Basic bXlBY2NvdW50Onh5enB3ZDEyMw==' \

--header 'content-type: application/json' \

--header 'accept: application/vnd.whatcounts-v1+json' \

--data '{

"subscriberId": 716094,

"email": "[email protected]",

"firstName": "Jon",

"customerKey": "jDoe3214"

}' \

--include

Response Body

The response returns a Success or Failure Error. Based on the first example above, the response returns a 0 for Success:

HTTP/1.1 200 OK

Server: serverName

Content-Type: application/json

Content-Length: 1

Date: Fri, 17 Mar 2018 12:54:44 GMT

0

Error Response

Error Response Codes include both Client Errors (4xx) and Server Errors (5xx). Descriptions of each can be found in Response Codes. An error will occur if List ID or Template ID are not found, if a Subscriber ID or Email/Customer Key is not supplied in the JSON, or if Subscriber is not found.

For example, if a Subscription does not exist for the Subscriber, the error would appear as:

{

"error": "Subscriber Not Found"

"status": "Not Found"

"statusCode": 404

}

Feature added in v13.00.0, Email Snapshot added in v15.00.00

The Send Message with Custom Content command allows you to senda single transactional style message of custom content to a Subscriber defined in the JSON.

Messages are individually created and sent but can be tracked together as a sticky campaign to collect data as a single campaign. To group your data into a single campaign, either use the Campaign Name argument or use a List with Sticky Campaigns enabled.

This command does not support the same features as the HTTP API, FTP API, or WebServices API Send commands, including the ability to define Google Analytics strings, Account Profile, or Subscriber Data for personalization.If your content includes Subscriber or Custom Data, you must create the subscriber first and import the data you wish to fill the content before using this command.

POST /msg

https://[siteurl]/rest/msg/sendWithContent/[listName]/?querystring

The following queries are supported:

format=[1,2,99],where 1=plain text, 2=html, and 99=MIME

campaignName=[string],

To track one-off message events, such as opens and click-throughs, define a campaign name. The Campaign Name can be no longer than 100 characters. A single list can have multiple campaigns by defining a different Campaign Name in a command.

respectOptout=[true,false],

If a subscriber has opted out, messages sent via the Send command will not be delivered. To override this restriction for transactional messages, such as order confirmations, set this argument to 'false'. DO NOT override opt outs for anything other than transactional messages, as this could be construed as spam.

subjectLine=[string], overrides the default Subject defined in the Template. Character limit is 48.

snapshot=[0,1],

If Email Snapshot is enabled for a realm, the snapshot flag providesthe ability to save and store HTML and PNG screenshots of emails. To store a snapshot, set this argument to '1'.

Request Body Parameters

The Send Message with Custom Content commandrequires the URI call with the List Name. Subject Line query is required. Optional Filters include Format, Campaign Name, Email Snapshot, and Opt Out parameters.

The query stringsare case sensitive and must be defined as in the example. If the query string is incorrect or missing, it is ignored and the command creates a Plain Text message without duplication, sending to the first subscriber found to match the posted JSON.

The command also requires the following in the Posted JSON:

Email: "email": [string]

HTML Content:"htmlContent": [string], Required if format=2,99

Plain Text Content:"textContent": [string], Required if format=1,99

Customer Key: "customerKey": [string], Required in Customer Key enabled realm

The following are optional in the Posted JSON:

First Name: "firstName": [string]

From Address: "fromEmail": [email], Required if not defined in List Properties

Reply To Address: "replyToAddress": [email], Required if not defined in List Properties

Format: "format": [1,2,99],where 1=plain text, 2=html, and 99=MIME

Request Body Example

Using Send Message with Custom Content with all arguments, line breaks in JSON for readability:

curl --request POST \

--url 'https://mail.mydomain.com/rest/msg/sendWithContent/myList?format=99&campaignName=myContentSend&respectOptout=true&snapshot=1&subjectLine=Read this content' \

--header 'authorization: Basic bXlBY2NvdW50Onh5enB3ZDEyMw==' \

--header 'content-type: application/json' \

--header 'accept: application/vnd.whatcounts-v1+json' \

--data '{

"email": "[email protected]",

"firstName": "Jon",

"fromEmail": "[email protected]",

"replyToEmail": "[email protected]",

"htmlContent": "<body><p>This is the HTML message content.</p></body>",

"textContent": "This is the Plain Text content."

}' \

--include

Using Send Message with Custom Content with all arguments for Customer Key enabled realm, line breaks in JSON for readability:

curl --request POST \

--url 'https://mail.mydomain.com/rest/msg/sendWithContent/myList?format=99&campaignName=myContentSend&respectOptout=true&subjectLine=Read this content' \

--header 'authorization: Basic bXlBY2NvdW50Onh5enB3ZDEyMw==' \

--header 'content-type: application/json' \

--header 'accept: application/vnd.whatcounts-v1+json' \

--data '{

"customerKey":"ck1232",

"email": "[email protected]",

"firstName": "Jon",

"fromEmail": "[email protected]",

"replyToEmail": "[email protected]",

"htmlContent": "<body><p>This is the HTML message content.</p></body>", "textContent": "This is the Plain Text content."

}' \

--include

Response Body

The response returns a Success or Failure Error. Based on the first example above, the response returns a 0 for Success:

HTTP/1.1 200 OK

Server: serverName

Content-Type: application/json

Content-Length: 1

Date: Fri, 17 Mar 2018 12:54:44 GMT

0

Error Response

Error Response Codes include both Client Errors (4xx) and Server Errors (5xx). Descriptions of each can be found in Response Codes. An error will occur if List ID is not found, if a Subscriber is not found, or content is not supplied in the JSON.

For example, if a Subscription does not exist for the Subscriber, the error would appear as:

{

"error": "Subscriber Not Found"

"status": "Not Found"

"statusCode": 404

}

Feature added in v13.04.0, Email Snapshot added in v15.00.00

The Send Message with Customer Key command allows you to senda single transactional style message to a Subscriber in a Customer Key enabled realm.

Messages are individually created and sent but can be tracked together as a sticky campaign to collect data as a single campaign. To group your data into a single campaign, either use the Campaign Name argument or use a List with Sticky Campaigns enabled.

This command does not support the same features as the HTTP API, FTP API, or WebServices API Send commands, including the ability to define Google Analytics strings, Account Profile, or Subscriber Data for personalization.

If your content includes Subscriber or Custom Data, use the Send Message with Subscriber Model and Names or Subscriber Model and IDs.

To send to a Subscriber in a non Customer Key enabled Realm, use the Send Message command.

POST /msg

https://[siteurl]/rest/msg/sendWithCustomerKey/[listName]/[templateName]/[customerKey]?querystring

The following queries are supported:

format=[1,2,99],where 1=plain text, 2=html, and 99=MIME

campaignName=[string],

To track one-off message events, such as opens and click-throughs, define a campaign name. The Campaign Name can be no longer than 100 characters. A single list can have multiple campaigns by defining a different Campaign Name in a command.

respectOptout=[true,false],

If a subscriber has opted out, messages sent via the Send command will not be delivered. To override this restriction for transactional messages, such as order confirmations, set this argument to 'false'. DO NOT override opt outs for anything other than transactional messages, as this could be construed as spam.

snapshot=[0,1],

If Email Snapshot is enabled for a realm, the snapshot flag providesthe ability to save and store HTML and PNG screenshots of emails. To store a snapshot, set this argument to '1'.

Request Body Parameters

The Send Message with Customer Key commandrequires the URI call with the List Name, Template Name, Subscriber Customer Key. Other Filters include Format, Campaign Name, Email Snapshot, and Opt Out parameters.

The query stringsare case sensitive and must be defined as in the example. If the query string is incorrect or missing, it is ignored and the command creates a Plain Text message without duplication, sending to the first subscriber found to match the posted JSON.

Request Body Example

Using Send Message with Customer Key with all arguments, line breaks in JSON for readability:

curl --request POST \

--url 'https://mail.mydomain.com/rest/msg/sendWithCustomerKey/myList/myTemplate/ck1232?format=99&campaignName=myContentSend&respectOptout=true&snapshot=1' \

--header 'authorization: Basic bXlBY2NvdW50Onh5enB3ZDEyMw==' \

--header 'content-type: application/json' \

--header 'accept: application/vnd.whatcounts-v1+json' \

--include

Response Body

The response returns a Success or Failure Error. Based on the first example above, the response returns a 0 for Success:

HTTP/1.1 200 OK

Server: serverName

Content-Type: application/json

Content-Length: 1

Date: Fri, 17 Mar 2018 12:54:44 GMT

0

Error Response

Error Response Codes include both Client Errors (4xx) and Server Errors (5xx). Descriptions of each can be found in Response Codes. An error will occur if List, Template, or Subscriber are not found.

For example, if a Subscription does not exist for the Subscriber, the error would appear as:

{

"error": "Subscriber Not Found"

"status": "Not Found"

"statusCode": 404

}

Feature added in v13.00.0, Email Snapshot added in v15.00.00

The Send Message command allows you to senda single transactional style message to a Subscriber.

Messages are individually created and sent but can be tracked together as a sticky campaign to collect data as a single campaign. To group your data into a single campaign, either use the Campaign Name argument or use a List with Sticky Campaigns enabled.

This command does not support the same features as the HTTP API, FTP API, or WebServices API Send commands, including the ability to define Google Analytics strings, Account Profile, or Subscriber Data for personalization.

If your content includes Subscriber or Custom Data, use the Send Message with Subscriber Model and Names or Subscriber Model and IDs.

To send to a Subscriber in a Customer Key enabled Realm, use the Send Message with Customer Key command.

POST /msg

https://[siteurl]/msg/send/[listName]/[templateName]/[email]/[firstName]?querystring

The following queries are supported:

format=[1,2,99],where 1=plain text, 2=html, and 99=MIME

campaignName=[string],

To track one-off message events, such as opens and click-throughs, define a campaign name. The Campaign Name can be no longer than 100 characters. A single list can have multiple campaigns by defining a different Campaign Name in a command.

respectOptout=[true,false],

If a subscriber has opted out, messages sent via the Send command will not be delivered. To override this restriction for transactional messages, such as order confirmations, set this argument to 'false'. DO NOT override opt outs for anything other than transactional messages, as this could be construed as spam.

snapshot=[0,1],

If Email Snapshot is enabled for a realm, the snapshot flag providesthe ability to save and store HTML and PNG screenshots of emails. To store a snapshot, set this argument to '1'.

Request Body Parameters

The Send Message commandrequires the URI call with the List Name, Template Name, Subscriber Email, and First Name. Other Filters include Format, Campaign Name, Email Snapshot, and Opt Out parameters.

The query stringsare case sensitive and must be defined as in the example. If the query string is incorrect or missing, it is ignored and the command creates a Plain Text message without duplication, sending to the first subscriber found to match the posted JSON.

Request Body Example

Using Send Message with all arguments, line breaks in JSON for readability:

curl --request POST \

--url 'https://mail.mydomain.com/rest/msg/send/myList/myTemplate/[email protected]/jon?format=99&campaignName=myContentSend&respectOptout=true&snapshot=1' \

--header 'authorization: Basic bXlBY2NvdW50Onh5enB3ZDEyMw==' \

--header 'content-type: application/json' \

--header 'accept: application/vnd.whatcounts-v1+json' \

--include

Response Body

The response returns a Success or Failure Error. Based on the first example above, the response returns a 0 for Success:

HTTP/1.1 200 OK

Server: serverName

Content-Type: application/json

Content-Length: 1

Date: Fri, 17 Mar 2018 12:54:44 GMT

0

Error Response

Error Response Codes include both Client Errors (4xx) and Server Errors (5xx). Descriptions of each can be found in Response Codes. An error will occur if List, Template or Subscriber are not found.

For example, if a Subscription does not exist for the Subscriber, the error would appear as:

{

"error": "Subscriber Not Found"

"status": "Not Found"

"statusCode": 404

}

Feature added in v13.00.0, Email Snapshot added in v15.00.00

The Send SMS Message to Sender Code command allows you to send an SMS Message to all Subscribers assigned to a Sender Code or Group. The command requires the following arguments: Command, Realm, Password, Sender Code, Message Name, and SMS Campaign Name.

api_web?r=myrealm&p=mypass&c=smssendmessagetosendercode&sender_code=120162701555&message_name=Welcome&name=WelcomeDaily

The command is ‘smssendmessagetosendercode', the realm is ‘myrealm’ and the password is ‘mypass’. The Welcome message content will be sent to all Subscribers in associated to the sender code '120162701555'.

Example

Using smssendmessagetosendercodewith all commands and arguments (please note the command is wrapped for display purposes only):

api_web?r=myrealm&p=mypass&c=smssendmessagetosendercode&sender_code=120162701555&message_name=Alert&name=201802Alert&group_name=Alerts

Successful results return:

SUCCESS: Sending message to subscriber was successful

Results

The Send SMS Message to Sender Code command outputs either a SUCCESS or FAILURE message.

Success

The command success message returns the SUCCESS message. The result format is:

SUCCESS: Sending message to subscriber was successful

Failure

Thecommand will fail if if the message is not foundor if an argument is invalid. The result format is:

FAILURE: [Reason]

NOTE: The command does not validate if the area code is valid or if the phone number does not exist.

Arguments

The command supports the following arguments:

Name

Req?

Description

Argument

Command

Yes

Defines the command to use.

cmd=smssendmessagetosendercode

c=smssendmessagetosendercode

Realm

Yes

Name of the realm to run the command. This is required, and the command will fail if the realm and password do not match.

realm=[realm_name]

r=[realm_name]

Password

Yes

Authentication code for API access. This is required, and the command will fail if the realm and password do not match.

pwd=[password]

p=[password]

Sender Code

Yes

Sender Code representing the message sender. A Sender Code is either a short code or number. It represents the 'from' field when deploying an SMS. The message recipient will see this sender on their mobile device when a message is received.

sender_code=[sender_code]

Message Name

Yes

The name of the pre-defined Message.

message_name=[string]

SMS Campaign Name

Yes

The name of the Campaign to associate for reporting.

name=[string]

SMS Group Name

The name of the subset of Subscribers in the Sender Code to target.

group_name=[string]

We are excited to release version 15.01.00 of theWhatCountsapplication. This release includesnew features,various improvements,and bug fixes.

New Features

Rest API: SMS send message call added to store an external id

Improvements

Users: Performance issue causing the View Users page to load slowly

Fixes

Publishing: DKIM failing causing Workflow messages to not deploy due to use of Admin VMTA

Creative Library: Unable to add a new theme in the Creative Library

Campaign Details: Edit Labels Modal Not Saving

Account Profiles: Unable to delete Account Profile fields in Realm Management

SMS: Unable to load data in Tracking tab

Bi-weekly release schedule resumes with this first release of the year.

New Features

Password History - do not allow reuse of passwords

Improvements

VMTA:

Send Test List emails using system configuration Admin VMTA

Send Workflow emails using system configuration Admin VMTA

View Tasks: Display more information for pending Workflow messages

Template Editor: Improve template load time for Realms with Media Manager files

Layout Editor: Improve layout load time for Realms with Media Manager files

Deliverability: Update page to no longer require Flash

List Details: In Search tab, update order of form inputs and table columns to match Subscriber Search

Bugs

HTTP API:

smssendmessagetophone call does not validate for opt-out

Create relational table does not store display_name and causes issues adding data via api

Rest API: SMS

sendMessageToPhone add validation

sendMessageToPhone update error details

sendMessageToSenderCode smsSubscriberCount reports 0, but at least 1 was sent

sendMessageToSenderCode does not send if group is not included

sendMessageToSenderCode update error details

sendMessageToSenderCode add validation

addSubscriberToSender add validation

addSubscriberToSender update error details

addSubscriberToSenderCode reports failure for invalid code but still creates subscription

addSubscriberToSenderCode returns invalid realmId

addPhoneToSenderCode update error details

addPhoneToSenderCode returns wrong realm_id

createMessage update error details

createMessage add validation

createMessage returns invalid realmId

Automation Definition: Deploy SMS action requires selections instead of acting as template

Batch Subscribe: Subscribing to multiple lists throws an error

Behavior Tracking: Question Mark ? added to end of resolved links

Layout Editor: Access to edit text lost after multi-clicking in Edge and Firefox

Creative Library Layout Editor: Upload Image tab displays folder selection twice

Glider UI Pages: Extra padding being added for Announcements when no announcement is showing

Campaign Search: Incorrect # Sent Values

List Definitions:

Sync does not update all fields with changes

Do not allow edit or delete lists created for Automation campaigns

View Lists goes to bin version of page

List Details: Do not allow add more than MAX Attributes

SMS Overview: ID numbers in table are displayed with commas

Templates: Dates should not be wrapped

Realm Products:

Error attempting to enable items in a realm where nothing is yet enabled

Popup warning modal appears unexpectedly

SMS:

Preset Message: Cannot reopen once Endpoint URL has been edited to replace first & with ?

Preset Message: Parameters not added correctly to Endpoint

Subscriptions without Group Name are not displayed

Subscriber Events: Bounce event detail displayed incorrectly

Sign Up Form Builder: Allow editing by PLA and Admin users

Calendar: End Dates are not honored as expected

View Tasks: Show progress for publishing task

Documentation

Login Errors : Update with Password History error

API HTTP SMS - Update pages to reflect improvements and fixes for validation, error reporting, and requirements

API HTTP - Update Send Commands to include new Email Snapshot feature Send, SubandSend, Launch, Schedule.

API FTP - SMS Save Update to reflect improvements and fixes for validation, error reporting, and requirements

API FTP - Update Send Commands to include new Email Snapshot feature Send, SubandSend, Launch, Schedule.

API Rest SMS - Update pages to reflect improvements and fixes for validation, error reporting, and requirements

14.17.00 - 09/19/2019

v14.17 resolves issues, provides UI improvements, and prepares for continued UI updates.

New Features

None

Improvements

List Compare: Make Max Scheduled text more visible (only available for specific accounts)

Template Editor: Add Optimize HTML button (only available for specific accounts)

Bugs

Automation Campaign: Deactivate modal does not reflect days set in Realm

History: Hide passwords for Logins

Impersonate: PLA cannot see realm just created

List Attributes: Validation not working

List Definitions: Copy modal is wider than others

Lists: Some pages still link to old Lists page

Edit Realm: PLA cannot see realm just created (cache issue)

Bounce Error Report: Multiple copies sent to admin email

Campaign Search: Large counts don't display properly

API Overview: Large counts don't display properly

Deployed Overview:Large counts don't display properly

14.17.01 - 09/19/2019

Bugs

WebServices API: Optimization for Subscription management

14.17.02 - 09/26/2019

Bugs

Impersonation: Issues seeing child realms when logged in as PLA

Calendar: Unable to delete Campaign Report from scheduled list

14.17.03 - 10/03/2019

Bugs

Create Realm: Parent Realm list is not in alpha-numeric order

Rest API: SMS sendMessageToPhone never reports success: true

List Details: Add Note that search is Exact if realm is set to Exact

The Send One-Off Message command allows you to send a single transactional style message to a subscriber. These messages are individually created and sent, but can be tracked together as a sticky campaign to collect data as a single campaign.

The Send command requires the following arguments: Command, Realm, Password, List, Template or Body, Format, and To.

api_web?r=myrealm&p=mypass&c=send&list_id=5&template_id=42&format=1&[email protected]

The command is ‘send’, the realm is ‘myrealm’ and the password is ‘mypass’. The list properties are defined in list with ID ‘5’, the content to send is in template with ID '42', and the message will be sent to the email address '[email protected]'.

Example

Using many commands and arguments (please note the command is wrapped for display purposes only):

api_web?r=myrealm&p=mypass&c=send&list_id=5&template_id=42&campaign_name=my+campaign&subject=New\%20Subject&format=2&[email protected]&vmta=myvmta&from=\%22Decorative\%22\%20\%[email protected]\%3E&[email protected]\%3E&data=email,first,custom_age ^[email protected],Jane,32

A message from List ‘5’ with plain text content from Template ‘42’ will be sent to ‘[email protected]’. If the Template contains tags for email, first, and the custom field age, then each will be filled with the data defined in the call, instead of data defined in the database. The From Address and the Subject defaults will be replaced for this message only. The message will be sent through the 'myvmta' IP.

If a campaign does not already exist, a new campaign called 'my campaign' will be created and all tracking data will be reported through it. If a campaign already exists, all tracking data will be added to the existing campaign.

Alternately, a message can be sent using the ‘plain_text_body’, ‘html_body’, and ‘subject’ arguments instead of defining a template:

api_web?r=myrealm&p=mypass&c=send&list_id=5&format=99&[email protected]&from="Decorative"\%20<[email protected]>&plain_text_body=This\%20is\%20plain\%20text\%20body&html_body=This\%20is\%20html\%20body&charset=ISO-8859-1&subject=Body\%20Subject

The results for either would appear as follows:

SUCCESS: mail will be sent to [email protected]

Customer Key Example

Some systems have the ability to define a unique Customer Key per subscriber. If your realm has Customer Key enabled, then you must include the customer_key in the command with the to email address. You can also include it in the data argument along with email. For example:

api_web?r=myrealm&p=mypass&c=send&list_id=5&template_id=42&campaign_name=my+campaign&subject=New\%20Subject&format=2&[email protected]&customer_key=11293&vmta=myvmta&from=\%22Decorative\%22\%20\%[email protected]\%3E&[email protected]\%3E&data=customer_key,email,first,custom_age^11293,[email protected],Jane,32

If the Customer Key is not included, the command will fail.

Customized Content

Since templates support the option of sending customized information, you can pass this data to the template through your Send command. By default, the Send command will use the data associated to the email address if a Subscriber record exists for the email. However, to override these fields use the "data" argument. Like other commands that support the data argument, you can pass general Subscriber Data and Custom Data, however it will not be saved to the database.

In addition, you can customize the List From and Reply To address using custom subscriber data fields. This can be accomplished by either setting the custom data in the List properties (From = "\%\%$myfrom\%\%" <\%\%$myemail\%\%>), or by setting the From and Reply To in the command:

from="\%25\%25$myfrom\%25\%25"\%20<\%25\%25$myemail\%25\%25>

When the message is sent, the publisher will grab the data stored in the Subscriber's custom data fields to fill in the address settings:

from: "My Custom From Address" <[email protected]>

Subscription vs. No Subscription

The To email address for the subscriber is always required, however the email address does not need to correspond to an existing subscriber. If an email address does not exist as a Subscriber or is not subscribed to the list, the message will be sent. A Subscriber Record will be created in the database with no Subscription. If the template requires custom data, you can send it through the command using the "data" argument. Custom data passed through the "send"command will only be used to populate the email and not saved to the Subscriber's record. If you require this data to be saved, use the Sub and Send command.

Tracking as Campaigns

By default the Subscribe and Send command sends a single message and does not track the resulting Subscriber initiated events, such as Opens, Clicks, and Unsubscribes. The Send is tracked as event with a Campaign ID of 0 and can only be reported using the Event Wizard, By Date option.

To track one-off messages as a campaign, you have two options. When you send your first message, a campaign will be created and all future data from messages sent to this list with the Subscribe and Send command will collect as part of this campaign.

Sticky Campaign

Use the Sticky Campaigns option in your List properties. Go toLISTS > VIEW LISTS. Select the list and then click the Advanced tab. Scroll to the bottom of the page and select the option under Sticky Campaigns labeled ‘Publish using the same (initial) campaign,’ and then click SAVE to save the settings.

You can view the Campaign Details by going to REPORTS > VIEW CAMPAIGNS and selecting the List.

Campaign Name

To identify a campaign and group the resulting tracking data, add the Campaign Name argument to the Send command. You can view the Campaign Details by going to REPORTS > VIEW CAMPAIGNS and selecting the List with the defined Campaign Name as the Alias.

Results

The Send command outputs either a SUCCESS or FAILURE message.

SUCCESS

The Send command returns the email address to which the message will be sent. The result format is:

SUCCESS: mail will be sent to [to email]

FAILURE

A Send command will fail for several reasons. The result format is:

FAILURE: [Reason]

Arguments

The Send command support the following arguments:

Name

Req?

Description

Argument

Command

Yes

Defines the command to use.

cmd=send

c=send

Realm

Yes

Name of the realm to run the command. This is required, and the command will fail if the realm and password do not match.

realm=[realm_name]

r=[realm_name]

Password

Yes

Authentication code for API access. This is required, and the command will fail if the realm and password do not match.

pwd=[password]

p=[password]

List

Yes

Identifier of the list properties to use. Required for List unsubscribeto function.

* List Name added in v13.0.0, coming soon

list_id=[list_id]

list_name[list\%20name]

From Address

Email address the message appears to be sent from. It can be a simple email address, or include a decorative portion in addition to the email address. This overrides the From Address set in the List properties.

from=[email address]

OR

from=["Decorative"\%20<email address>]

Reply To Address

Email address the message replies will be sent to. It can be a simple email address, or can include a decorative portion in addition to the email address. This overrides the Reply to Address set in the List properties.

reply_to_address=[email address]

OR

reply_to_address=["Decorative"\%20<email address>]

Errors To Address

Mailbox to catch error responses, such as bounce messages. Bounces are not tracked using the Send command, because the bounce hander requires campaign information.

errors_to=[bounce address]

Sender Address

Email address that will appear as the Sender in some email applications. This is useful for some ISPs that require the Sender field in the message header. The from address in the message will appear as: [Sender Address] on behalf of [From Address]

sender=[email address]

OR

sender=["Decorative"\%20<email address>]

Send To Address

Yes

Email address to send the message.

to=[email address]

CC To Address

Email address to send a copy of the message.

cc=[email address]

Template

*

Identifier of the template content to send. If no template defined in the call, the default template defined in the List properties will be used. If no template is defined in list, the body must be manually defined. In the template, both Plain Text and HTML must be defined in order to send MIME.

* Template Name added in v13.0.0, coming soon

template_id=[template_id]

template_name=[template\%20name]

Body Plain Text

*

Custom defined message content to use in place of a Template’s Plain-Text content. In order for URLs to track for click-throughs, the URL must include http://, and the Sticky Campaigns option must be enabled in the Advanced List Properties.

plain_text_body=[text]

Body HTML

*

Custom defined message content to use in place of a Template’s HTML content.In order for URLs to track for click-throughs, the URL must include http://, and the Sticky Campaigns option must be enabled in the Advanced List Properties.

html_body=[text]

Subject

*

Subject line of the message to send. This overrides the default Subject defined in the Template. Character limit is 48.

subject=[text]

Format

Yes

To specify the format of the email message, set Format to the corresponding value:

1= send Plain Text only

2 = send HTML only

99 = send Multipart MIME

format=[1,2,99]

Campaign Name

To track one-off message events, such as opens and click-throughs, define a campaign name. The Campaign Name can be no longer than 100 characters.A single list can have multiple campaigns by defining a different Campaign Name in a command.

You can view the results as a single campaign byusing the Sticky Campaigns option in the Advanced List Properties.

See Track as Campaigns above for more information.

campaign_name=[campaign_name]

Virtual MTA

Name of the Virtual MTA IP address through which to deploy the message. If not defined, the VTMA set in the List properties will be used.

vmta=[vmta_name]

Duplicate

If subscribers exist with the same email address and different first name, you must indicate which subscriber should receive the message using first name and duplicate setting.

first_name=[first_name]&dup=[0,1]

DEFAULT==0

Ignore Optout

If a subscriber has opted out, messages sent via the send command will not be delivered. To override this restriction for transactional messages, such as order confirmations, set this argument to '1'. DO NOT override optouts for anything other than transactional messages, as this could be construed as spam.

ignore_optout=[0,1]

DEFAULT==0

Character Set Encoding

Character set to use with custom content or template content. If not defined, the command will use the character set defined in the template. Examples include: charset=utf-8, charset=ISO-8859-1, charset=shift-jis

charset=[encoding]

Account Profile

To use an Account Profile other than that assigned to the list, define the Account Profile ID.

Account Profile support added in v12.03.0.

acct_pro_id=[account_profile_id]

Data

Data fields are optional to pass data into \%\%$[field]\%\% tags in the template, such as ‘email’ or custom fields, if not already stored in the database.

data=[fields]

d=[fields]

Email Snapshot

Email Snapshot will create andstore the HTML and image screenshot of each message sent, including subscriber-specific personalization. If your Realm is enabled for Email Snapshot, to store a copy of each message, set the'snapshot' argument to 1.

Email Snapshot support added in v15.00.00.

snapshot=[0,1]

Google Analytics

To include system managed Analytics tags in your tracking URLs, the 'ga' argument must be set to 1. In addition, the &campaign_namemust be included in the argument or the List must be set to use Sticky Campaigns to convert the URLs to tracked URLs.

The UTM arguments for the first send to the List or Campaign are stored to use for all future campaigns.If no UTM arguments are included in the first command, then the default UTM settings from the Realm will be used.

To customize the UTM setting for the specific command, add the &utm_ tag followed by a string value.

To ignore the default value from the Realm, use the &utm Remove argument set to 1.

For example, to use the default source, medium and campaign, but use a custom content, and blank term, use the following set of arguments:

&campaign_name=GoogleEnabled&ga=1&utm_content=Custom\%20Content

&utm_term_remove=1

Google Analytics support added in v12.13.0.

&ga=[0,1]

&utm_source=[string]

&utm_medium=[string]

&utm_campaign=[string]

&utm_content=[string]

&utm_term=[string]

&utm_source_remove=[0,1]

&utm_medium_remove=[0,1]

&utm_campaign_remove=[0,1]

&utm_content_remove=[0,1]

&utm_term_remove=[0,1]

The Subscribe and Send One-Off Message command allows you to subscribe an email address to a list and send a single transactional style message to the subscriber. These messages are individually created and sent, but can be tracked together as a sticky campaign to collect data as a single campaign.

The Subscribe and Send command requires the following arguments: Command, Realm, Password, List, Template or Body, Format, To, and Data with Email.

api_web?r=myrealm&p=mypass&c=subandsend&list_id=5&template_id=42&format=1&[email protected]&data=email^[email protected]

The command is ‘subandsend’, the realm is ‘myrealm’ and the password is ‘mypass’. The list properties are defined in list with ID ‘5’, the content to send is in template with ID '42', a subscription will be created for the email address '[email protected]' and the message will then be sent to the subscriber.

Example

Using many commands and arguments (please note the command is wrapped for display purposes only):

api_web?r=myrealm&p=mypass&c=subandsend&list_id=5&template_id=42&campaign_name=my+campaign&subject=New\%20Subject&format=2&[email protected]&vmta=myvmta&from=\%22Decorative\%22\%20\%[email protected]\%3E&[email protected]\%3E&data=email,first,custom_age^[email protected],Jane,32

If it doesn't already exist, a new subscription will be created for ‘[email protected]’ and the first name and custom age will be stored. If the subscriber already exists, the data will be updated in the subscriber record.

Once the subscription and subscriber are updated, a message from List ‘5’ with HTMLcontent from Template ‘42’ will be sent to ‘[email protected]’. The From Address and the Subject defaults will be replaced for this message only. The message will be sent through the 'myvmta' IP.

If a campaign does not already exist, a new campaign called 'my campaign' will be created and all tracking data will be reported through it. If a campaign already exists, all tracking data will be added to the existing campaign.

Alternately, a message can be sent using the ‘plain_text_body’, ‘html_body’, and ‘subject’ arguments instead of defining a template if the List is set to track as Sticky Campaign:

api_web?r=myrealm&p=mypass&c=send&list_id=5&format=99&[email protected]&from="Decorative"\%20<[email protected]>&plain_text_body=This\%20is\%20plain\%20text\%20body&html_body=This\%20is\%20html\%20body&charset=ISO-8859-1&subject=Body\%20Subject&data=email,first^[email protected],Jane

The results for either would appear as follows:

SUCCESS: mail will be sent to [email protected]

Customer Key Example

Some systems have the ability to define a unique Customer Key per subscriber. If your realm has Customer Key enabled, then you must include the customer_key in the command with the to email address. You must also include it in the data argument along with email. For example:

api_web?r=myrealm&p=mypass&c=subandsend&list_id=5&template_id=42&campaign_name=my+campaign&subject=New\%20Subject&format=2&[email protected]&customer_key=11293&vmta=myvmta&from=\%22Decorative\%22\%20\%[email protected]\%3E&[email protected]\%3E&data=customer_key,email,first,custom_age^11293,[email protected],Jane,32

If the Customer Key is not included, the command will fail in one of two possible ways. If customer_key missing from Data:

FAILURE: Total Records Processed 1, Total Subscriptions 0, Records Added 0, Records Updated 0, Records Ignored (Optout Error) 0, Records Failed Other Error 1

If &customer_key argument is missing:

FAILURE:missing customer key

Customized Content

Since templates support the option of sending customized information, you can pass this data to the template through your Send command. By default, the Send command will use the data associated to the email address if a Subscriber record exists for the email. However, to update and override these fields use the "data" argument. Like other commands that support the data argument, you can pass general Subscriber Data and Custom Data, and it will be saved to the database.

In addition, you can customize the List From and Reply To address using custom subscriber data fields. This can be accomplished by either setting the custom data in the List properties (From = "\%\%$myfrom\%\%" <\%\%$myemail\%\%>), or by setting the From and Reply To in the command:

From="\%25\%25$myfrom\%25\%25"\%20<\%25\%25$myemail\%25\%25>

When the message is sent, the publisher will grab the data stored in the Subscriber's custom data fields to fill in the address settings:

From: "My Custom From Address" <[email protected]>

Subscription vs. No Subscription

The To email address for the subscriber is always required, however the email address does not need to correspond to an existing subscriber. If an email address does not exist as a Subscriber or is not subscribed to the list, a subscription will be created and the message will be sent. If you do not wish to subscribe the email address, use the simple Send command instead.

Tracking as Campaigns

By default the Subscribe and Send command sends a single message and does not track the resulting Subscriber initiated events, such as Opens, Clicks, and Unsubscribes. The Send is tracked as event with a Campaign ID of 0 and can only be reported using the Event Wizard, By Date option.

To track one-off messages as a campaign, you have two options. When you send your first message, a campaign will be created and all future data from messages sent to this list with the Subscribe and Send command will collect as part of this campaign.

Sticky Campaign

Use the Sticky Campaigns option in your List properties. Go toLISTS > VIEW LISTS. Select the list and then click the Advanced tab. Scroll to the bottom of the page and select the option under Sticky Campaigns labeled ‘Publish using the same (initial) campaign,’ and then click SAVE to save the settings.

You can view the Campaign Details by going to REPORTS > VIEW CAMPAIGNS and selecting the List.

Campaign Name

To identify a campaign and group the resulting tracking data, add the Campaign Name argument to the Send command. You can view the Campaign Details by going to REPORTS > VIEW CAMPAIGNS and selecting the List with the defined Campaign Name as the Alias.

Results

The Subscribe and Send command outputs either a SUCCESS or FAILURE message.

SUCCESS

The Subscribe and Send command returns the email address to which the message will be sent. The result format is:

SUCCESS: mail will be sent to [to email]

FAILURE

A Subscribe and Send command will fail for several reasons, such as if the email or customer key are missing from the Data argument. The result format is:

FAILURE: [Reason]

Arguments

The Subscribe and Send command supports the following arguments:

Name

Req?

Description

Argument

Command

Yes

Defines the command to use.

cmd=subandsend

c=subandsend

Realm

Yes

Name of the realm to run the command. This is required, and the command will fail if the realm and password do not match.

realm=[realm_name]

r=[realm_name]

Password

Yes

Authentication code for API access. This is required, and the command will fail if the realm and password do not match.

pwd=[password]

p=[password]

List ID

Yes

Identifier of the list properties to use.

list_id=[list_id]

From Address

Email address the message appears to be sent from. It can be a simple email address, or include a decorative portion in addition to the email address. This overrides the From Address set in the List properties.

from=[email address]

OR

from=["Decorative"\%20<email address>]

Reply To Address

Email address the message replies will be sent to. It can be a simple email address, or can include a decorative portion in addition to the email address. This overrides the Reply to Address set in the List properties.

reply_to_address=[email address]

OR

reply_to_address=["Decorative"\%20<email address>]

Errors To Address

Mailbox to catch error responses, such as bounce messages. Bounces are not tracked using the Send command, because the bounce hander requires campaign information.

errors_to=[bounce address]

Sender Address

Email address that will appear as the Sender in some email applications. This is useful for some ISPs that require the Sender field in the message header. The from address in the message will appear as:

[Sender Address] on behalf of [From Address]

sender=[email address]

OR

sender=["Decorative"\%20<email address>]

Send To Address

Yes

Email address to send the message.

to=[email address]

Customer Key

*

Subscriber Customer Key, required in accounts in which Customer Key is enabled only.

customer_key=[ck]

Template ID

*

Identifier of the template content to send. If no template id defined in the call, the default template defined in the List properties will be used. If no template is defined, the body must be manually defined. In the template, both Plain Text and HTML must be defined in order to send MIME.

template_id=[template_id]

Body Plain Text

*

Custom defined message content to use in place of a Template’s Plain-Text content.In order for URLs to track for click-throughs, the URL must include http://, and the Sticky Campaigns option must be enabled in the Advanced List Properties.

plain_text_body=[text]

Body HTML

*

Custom defined message content to use in place of a Template’s HTML content.In order for URLs to track for click-throughs, the URL must include http://, and the Sticky Campaigns option must be enabled in the Advanced List Properties.

html_body=[text]

Subject

*

Subject line of the message to send. This overrides the default Subject defined in the Template. Character limit is 48.

subject=[text]

Format

Yes

To specify the format of the email message, set Format to the corresponding value:

1= send Plain Text only

2 = send HTML only

99 = send Multipart MIME

format=[1,2,99]

Campaign Name

To track one-off message events, such as opens and click-throughs, define a campaign name. The Campaign Name can be no longer than 100 characters.A single list can have multiple campaigns by defining a different Campaign Name in a command.

You can view the results as a single campaign byusing the Sticky Campaigns option in the Advanced List Properties.

See Track as Campaigns above for more information.

campaign_name=[campaign_name]

Virtual MTA

Name of the Virtual MTA IP address through which to deploy the message. If not defined, the VTMA set in the List properties will be used.

vmta=[vmta_name]

Duplicate

If subscribers exist with the same email address and different first name, you must indicate which subscriber should receive the message using first name and duplicate setting.

first_name=[first_name] &dup=[0,1]

DEFAULT==0

Ignore Optout

If a subscriber has opted out, messages sent via the send command will not be delivered. To override this restriction for transactional messages, such as order confirmations, set this argument to '1'. DO NOT override opt outs for anything other than transactional messages, as this could be construed as spam.

ignore_optout=[0,1]

DEFAULT==0

Character Set Encoding

Character set to use with custom content or template content. If not defined, the command will use the character set defined in the template. Examples include: charset=utf-8, charset=ISO-8859-1, charset=shift-jis

charset=[encoding]

Account Profile

To use an Account Profile other than that assigned to the list, define the Account Profile ID.

Account Profile support added in v12.03.0.

acct_pro_id=[account_profile_id]

Data

Yes

To create a subscription, the Data argument is required with the Email Address (and Customer Key if enabled for Account) defined. If the Email Address is not included, the message can send, but the Subscriber Data will not be stored in the database. For example:

data=email^[email protected]

data=customer_key,email^123abc,[email protected]

Data fields are optional to store with the subscriber and then pass data into \%\%$[field]\%\% tags in the template, such as ‘first_name’ or custom fields. For example:

data=email,first_name,custom_gender^[email protected],Jane,f

data=[fields]

d=[fields]

Email Snapshot

Email Snapshot will create andstore the HTML and image screenshot of each message sent, including subscriber-specific personalization. If your Realm is enabled for Email Snapshot, to store a copy of each message, set the'snapshot' argument to 1.

Email Snapshot support added in v15.00.00.

snapshot=[0,1]

Google Analytics

*COMING SOON* To include system managed Analytics tags in your tracking URLs, the 'ga' argument must be set to 1. In addition, the &campaign_namemust be included in the argument or the List must be set to use Sticky Campaigns to convert the URLs to tracked URLs.

The UTM arguments for the first send to the List or Campaign are stored to use for all future campaigns.If no UTM arguments are included in the first command, then the default UTM settings from the Account will be used.

To customize the UTM setting for the specific command, add the &utm_ tag followed by a string value.

To ignore the default value from the Account, use the &utm Remove argument set to 1.

For example, to use the default source, medium and campaign, but use a custom content, and blank term, use the following set of arguments:

&campaign_name=GoogleEnabled&ga=1&utm_content=Custom\%20Content

&utm_term_remove=1

Google Analytics support will be added soon.

&ga=[0,1]

&utm_source=[string]

&utm_medium=[string]

&utm_campaign=[string]

&utm_content=[string]

&utm_term=[string]

&utm_source_remove=[0,1]

&utm_medium_remove=[0,1]

&utm_campaign_remove=[0,1]

&utm_content_remove=[0,1]

&utm_term_remove=[0,1]

The Launch command allows you to deploy a campaign to a List of subscribers or a Segment of a List. It requires the following arguments: Command, Realm, Password, List and Format.

api_web?r=myrealm&p=mypass&c=launch&list_id=5&format=2

The command is ‘launch’, the realm is ‘myrealm’ and the password is ‘mypass’. The list properties are defined in list with ID ‘5’, the template content to send is defined in the list properties, and all subscribers in the list will receive the HTML contentformat.

Before deploying a campaign, every email address to receive the message must be subscribed to the list. If a subscriber does not exist or is not subscribed to the list, no message will be sent to that subscriber. In order to send a message to a non-subscriber (such as an order confirmation), please use the send command.

When you call the Launch command, a campaign iscreated and all data collects as part of this campaign. However, the Launch command does not check to ensure subscribers exist in the list or list segment. If there are 0 subscribers, the command will return SUCCESS, but no campaign will deploy.

Return Count

The Launch command can also return the subscriber count for the campaign by using the command 'launchwithcount'. It works the same as the basic 'launch' but also returns the number of pieces sent.

Super List

Prior to v12.06.0, Launch deploys campaigns of type Normal only and does notdeploy a Super List. Super Lists can only be deployed through the user interface or in versions before v12.06.0.

Customized Content

Templates support the option of sending customized information. While you can pass in custom data with the Send command, the Launch command can only use the data associated to each subscriber for each message.

However, you can customize the List From and Reply To address using custom subscriber data fields. This can be accomplished by setting the custom data in the List properties (From = "\%\%$myfrom\%\%" <\%\%$myemail\%\%>).

When the message is sent, the publisher will grab the data stored in the Subscriber's custom data field to fill in the address settings:

From: "My Custom From Address" <[email protected]>

Example

Using all commands and arguments (please note the command is wrapped for display purposes only):

api_web?c=launch&r=myrealm&p=mypass&list_id=5&template_id=42&seed_list_id=6&subject=New\%20Subject&format=99&vmta=myvmta&segmentation_id=9&campaign_alias=Test&email_phase=convert&email_type=service&email_category=reengagement&[email protected]&delivery=0

A message from List ‘5’ with MIME merged content from Template ‘42’ will be sent to all subscribers that match the rules defined in segmentation rule ‘9’. The default Template Subject will be replaced in the resulting message. The message will be sent through the 'myvmta' IP. Successful results return:

SUCCESS:

Alternately, to send an A/B Test, use the command in the following format:

api_web?c=launch&r=myrealm&p=mypass&ab_definition_id=132&[email protected]

Results

The Launch command outputs either a SUCCESS or FAILURE message.

SUCCESS

The basic Launch command success message is the simple word 'SUCCESS'. The result format is:

SUCCESS:

The Launch command with the additional 'withcount' returns the number of subscribers currently matching the List Count minus any Segment or Suppression rules. The result format is:

SUCCESS: [number_pieces_sent]

The Launch command with the additional 'return_task_id' returns the identification number of the list and the task created for the campaign to launch. The result format is:

SUCCESS: list_id [list_id] launched. Task ID: [task_id]

FAILURE

A Launch command will fail for several reasons, such as if the list does not exist or the From Address is missing. The result format is:

FAILURE: [Reason]

Arguments

The Launch commands support the following arguments:

Name

Req?

Description

Argument

Command

Yes

Defines the command to use.

cmd= [launch, launchwithcount]

c=[launch, launchwithcount]

*listrun and listrunwithcount prior to v10 also acceptable

Realm

Yes

Name of the realm to run the command. This is required, and the command will fail if the realm and password do not match.

realm=[realm_name]

r=[realm_name]

Password

Yes

Authentication code for API access. This is required, and the command will fail if the realm and password do not match.

pwd=[password]

p=[password]

List ID

Yes

Identifier of the list properties to use.

list_id=[list_id]

Template ID

Identifier of the template content to send. If no template id defined in the call, the default template defined in the List properties will be used. If no template is defined there, the call will fail. In the template, both formats must be defined in order to send MIME.

template_id=[template_id]

Subject

Subject line of the message to send. This overrides the default Subject defined in the Template. Character limit is 48.

subject=[text]

Seed List

To seed a campaign with test addresses from a Seed List, set the seed_list id.

seed_list_id=[seed_list_id]

Segmentation Rule

Identifier of the segmentation rule to use to limit the subscribers. If no segmentation rule is specified, the campaign will deploy to every subscriber in the List.

segmentation_id=[segmentation_rule_id]

Format

Yes

To specify the format of the email messages, set Format to the corresponding value:

1= send Plain Text only

2 = send HTML only

99 = send Multipart MIME

format=[1,2,99]

Campaign Alias

An optional text string to help you distinguish the campaign from others deployed from the same list.

campaign_alias=[text]

Send RSS

By default, campaigns will send to all subscribers, including any RSS subscribers. to prevent messages from deploying to RSS Subscribers, set to 0.

* Removed in v11.16.0

target_rss=[0,1]

DEFAULT==1

Virtual MTA

Name of the Virtual MTA IP address through which to deploy the messages. If not defined, the VTMA set in the List properties will be used.

vmta=[vmta_name]

A/B Definition

Identifier of the A/B Test Definition to deploy to subscribers. List, Template, and Segment are not required or used when A/B Definition is used because the List, Template, and Segment are defined in the A/B Definition.

ab_defintion_id=[ab_definition_id]

A/B Deployed By Email

Email address of the realm User deploying the A/B test. if the email address does not match a User in the realm, then the command will fail. Required when sending A/B Test.

deployed_by_email=[email address]

Return Task ID

On a successful launch, return the idnetifier for the created task if set to 1.

return_task_id=[0,1]

DEFAULT==0

Seed Delivery

To seed a campaign with email addresses associated with monitored mailboxes (ie: Return Path), set Delivery to 1. This feature is limited in its availability and must be enabled in your Realm settings. When the campaign is complete, the results of the Deliverability Report are available in the Campaign Details.

delivery=[0,1]

DEFAULT==0

Released in v10.8.0

Send Notification

After the campaign has completed, a notification email will be sent to the specified email address.

notify_email=[email address]

Email Campaign Labels

Define labels to associate the campaign for later reporting, including Email Phase, Type, and Category. Labels are optional. The label name must match a valid label of the specified type already defined in your Account. See Get Email Labels to get a list of defined labels of each type in your Account.

* Email Campaign Label support added in v12.06.0.

email_phase=[phase_name]

email_type=[type_name]

email_category=[category_name]

Account Profile

To use an Account Profile other than that assigned to the list, define the Account Profile ID.

Account Profile support added in v12.03.0.

acct_pro_id=[account_profile_id]

Email Snapshot

Email Snapshot will create andstore the HTML and image screenshot of each message sent, including subscriber-specific personalization. If your Realm is enabled for Email Snapshot, to store a copy of each message, set the'snapshot' argument to 1.

Email Snapshot support added in v15.00.00.

snapshot=[0,1]

Google Analytics

To include Analytics tags in your tracking URLs, the 'ga' argument must be set to 1.

If no UTM arguments are included in the command, then the default UTM settings from the Account will be used.

To customize the UTM setting for the specific command, add the &utm_ tag followed by a string value.

To ignore the default value from the Account, use the &utm Remove argument set to 1.

For example, to use the default source, medium and campaign, but use a custom content, and blank term, use the following set of arguments:

&campaign_name=GoogleEnabled&ga=1&utm_content=Custom\%20Content

&utm_term_remove=1

Google Analytics support added in v12.13.0.

&ga=[0,1]

&utm_source=[string]

&utm_medium=[string]

&utm_campaign=[string]

&utm_content=[string]

&utm_term=[string]

&utm_source_remove=[0,1]

&utm_medium_remove=[0,1]

&utm_campaign_remove=[0,1]

&utm_content_remove=[0,1]

&utm_term_remove=[0,1]

The Schedule Campaign command allows you to set a campaign to deploy at a specific date and time on a one time or recurring basis.

The Schedule Campaign command requires the following arguments: Command, Realm, Password, List, Format, Start Date and Time.

api_web?r=myrealm&p=mypass&c=schedule_deployment&list_id=5&format=1&start_month=09&start_day=20&start_year=2012&hour=11&minute=30

The command is ‘schedule_deployment’, the realm is ‘myrealm’ and the password is ‘mypass’. The list properties are defined in list with ID ‘5’, the template content to send is defined in the list properties, and all subscribers in the list will be sent the Plain Text format at 11:30 am on September 20, 2012.

Before deploying a campaign, every email address to receive the message must be subscribed to the list. If a subscriber does not exist or is not subscribed to the list, no message will be sent to that subscriber.

The Schedule Campaign command does not check to ensure subscribers exist in the list or list segment. If there are 0 subscribers, the command will return SUCCESS and be scheduled. If there are no subscribers at run time, no campaign will deploy and a failure message will be sent to the Notification email address.

Return Count

The Schedule Campaign command can also return the subscriber count for the campaign by using the command 'scheduledeploymentreturncount'. It works the same as the basic 'schedule_deployment' but also returns the number of pieces that would send if the campaign were to launch immediately. **

Super List

Prior to v12.05.0, Schedule Campaigndeploys campaigns of type Normal only and does notdeploy a Super List. Super List deployment can only be scheduledthrough the user interface or in versions before v12.05.0.

Time Zone

Schedule Campaign Start and End times are based on the system time zone, and ignore the timezone set for the Account. For example, if the database timezone is set to PST, but the Account uses EST when displaying the time in the user interface, the API will always schedule based on the PST time. Your campaign scheduled to run at 12:30 PM will deploy at 12:30 PM PST / 3:30 PM EST.

As of 12.06.0, you may select to use the Account's timezone instead with the use_timezone attribute. If use_timezone = 1, then your campaign scheduled to run at 12:30 PM will deploy at 12:30 PM EST.

Customized Content

Templates support the option of sending customized information. While you can pass in custom data with the Send command, the Schedule Campaign command will only use the data associated to each subscriber for each message.

However, you can customize the List From and Reply To address using custom subscriber data fields. This can be accomplished by setting the custom data in the List properties (From = "\%\%$myfrom\%\%" <\%\%$myemail\%\%>).

When the message is sent, the publisher will grab the data stored in the Subscriber's custom data field to fill in the address settings:

From: "My Custom From Address" <[email protected]>

Example

Using all commands and arguments (please note the command is wrapped for display purposes only):

api_web?c=schedule_deployment&r=myrealm&p=mypass&list_id=5&seed_list_id=6&template_id=42&format=99&segmentation_id=9&suppression_list=suppress.txt&set_data_macro_id=40&start_month=09&start_day=26&start_year=2012&hour=09&minute=30&no_end_date=1&repeat_frequency=3&monday=1&wednesday=1&[email protected]&campaign_alias=Test&email_phase=convert&email_type=service&email_category=reengagement&delivery=0&use_timezone=1&verbose=1

A message from List ‘5’ with MIME content from Template ‘42’ will be sent to all subscribers that match the rules defined in segmentation rule ‘9’ and are not in the suppression list 'suppress.txt'. The message will repeat weekly on Monday and Wednesday at 9:30 am starting on September 26, 2012. Successful results return:

SUCCESS

Results

The Schedule Campaign command outputs either a SUCCESS or FAILURE message.

SUCCESS

The Schedule Campaign command success message is the simple word 'SUCCESS'. The result format is:

SUCCESS

The Schedule Campaign command with the additional 'returncount' returns the number of subscribers currently matching the List Count minus any Segment or Suppression rules.** The result format is:

SUCCESS: [count]

FAILURE

A Schedule Campaign command will fail for several reasons, such as if the List or Template does not exist, or the List is missing a From address. The result format is:

FAILURE: [Reason]

Arguments

The command support the following arguments:

Name

Req?

Description

Argument

Command

Yes

Defines the command to use.

cmd=[schedule_deployment, scheduledeploymentreturncount]

c=[schedule_deployment,

scheduledeploymentreturncount]

Realm

Yes

Name of the realm to run the command. This is required, and the command will fail if the realm and password do not match.

realm=[realm_name]

r=[realm_name]

Password

Yes

Authentication code for API access. This is required, and the command will fail if the realm and password do not match.

pwd=[password]

p=[password]

List ID

Yes

Identifier of the list properties to use.

list_id=[list_id]

Template ID

Yes

Identifier of the template content to send. If no template id defined in the call, the default template defined in the List properties will be used. If no template is defined there, the call will fail. In the template, both formats must be defined in order to send MIME.

template_id=[template_id]

Format

Yes

To specify the format of the email messages, set Format to the corresponding value:

0 = send Subscriber Selected Format

1= send Plain Text only

2 = send HTML only

99 = send Multipart MIME

format=[0,1,2,99]

Segmentation Rule

Identifier of the segmentation rule to use to limit the subscribers. If no segmentation rule is specified or is set to 0, the campaign will deploy to every subscriber in the List.

segmentation_id=[segmentation_rule_id]

Seed List

To seed a campaign with test addresses from a Seed List, set the seed_list id.

seed_list_id=[seed_list_id]

Suppression List

To suppress subscribers in the list from recieving the message, use the Suppression List by defining the File Name of the Suppression LIst.

suppression_list=[suppression file name]

Set Data Macro

To set subscriber data when a campaign is deployed, define the Set Data Macro ID.

set_data_macro_id=[set_data_macro_id]

Campaign Alias

An optional text string to help you distinguish the campaign from others deployed from the same list.

campaign_alias=[text]

Send RSS

By default, campaigns will send to all subscribers, including any RSS subscribers. to prevent messages from deploying to RSS Subscribers, set to 0.

* Removed in v11.16.0

target_rss=[0,1]

DEFAULT==1

Limit*

To send to only a specific number of subscribers, define a limit. This is useful for testing message content to a group of test subscribers. Limit is not supported when sending an AB Definition.

limit=[integer]

Fillin Fields*

If the List and Template contain fillin fields, set the values by defining the fillin_name and fillin_values, where N is a number starting with 0 up to 9 (limited to 10 fillin fields at this time). For example:

&fillin_name0=Subject &fillin_value0=Welcome &fillin_name1=City &fillin_value1=Seattle

**NOTE: If a fillin field has been defined as Required in a List, Template, or Article, then it must be defined in the Schedule Campaign command, otherwise the command will fail with the following error:

FAILURE: missing value for required fillin field [fillin field name]

&fillin_nameN=[fillin_field_name] &fillin_valueN=[fillin_field_value]

Seed Delivery

To seed a campaign with email addresses associated with monitored mailboxes (ie: Return Path), set Delivery to 1. This feature is limited in its availability and must be enabled in your Realm settings. When the campaign is complete, the results of the Deliverability Report are available in the Campaign Details.

delivery=[0,1]

DEFAULT==0

Released in v10.8.0

Send Notification

After the campaign has completed, a notification email will be sent to the specified email address.

notify_email=[email address]

Start Date

Yes

The date to start sending the campaign. If it is not defined, the campagain will be immediately deployed.

mm = two digit number for the month, 01 to 12

dd = two digit number for the day, 01 to 31

yyyy = four digit year

start_month=[mm]

start_day=[dd]

start_year=[yyyy]

Start Time

Yes

The time to run the campaign. If it is not defined, the campagain will be immediately deployed.

hh = two digit number for the hour in twenty four hour notation, 00 to 23

mm = two digit number for the minute, 00 to 59

hour=[hh]

minute=[mm]

End Date

The date to stop sending the campaign. If it is not defined, the campagain will be immediately deployed.

mm = two digit number for the month, 01 to 12

dd = two digit number for the day, 01 to 31

yyyy = four digit year

end_month=[mm]

end_day=[dd]

end_year=[yyyy]

No End Date

To schedule a repeating campaign that never ends, set to 1 and do not define the End Date. If set to 1, any defined End Date will be ignored.

no_end_date=[0,1]

DEFAULT==0

Workflow Send Time

Specify the number of hours prior to the scheduled time to send the Workflow message. This is only valid if Workflow is enabled for the list.

hh = one or two digit number to indicate the hour from 0 to 72

0 = send at scheduled time

workflow_send_time=[hh]

DEFAULT==0

Repeat Frequency

To schedule a repeating campaign, set the frequency. If set to weekly, you must also set the week day to 1 for each day to send.

0 = one time, do not repeat

1 = hourly

2 = daily

3 = weekly

4 = monthly

6 = every 15 minutes

7 = every 30 minutes

repeat_frequency=[frequency]

DEFAULT==0

sunday=[0,1]

monday=[0,1]

tuesday=[0,1]

wednesday=[0,1]

thursday=[0,1]

friday=[0,1]

saturday=[0,1]

Use Time Zone

If your Account is set to use a timezone other than the default server timezone (usually PST), the campaign is scheduled using the default servers timezone To use the Account specific timezone instead, set to 1.

*Time Zone option added in v12.06.0

use_timezone=[0,1]

DEFAULT == 0

Verbose

Set verbose to true to output XML formatted settings for the scheduled campaign. By default, this flag is set to false.

verbose=[0,1]

return_params=[0,1]

DEFAULT==0

Email Campaign Labels

Define labels to associate the campaign for later reporting, including Email Phase, Type, and Category. Labels are optional. The label name must match a valid label of the specified type already defined in your Account. See Get Email Labels to get a list of defined labels of each type in your Account.

* Email Campaign Label support added in v12.06.0.

email_phase=[phase_name]

email_type=[type_name]

email_category=[category_name]

Account Profile

To use an Account Profile other than that assigned to the list, define the Account Profile ID.

* Account Profile support added in v12.03.0.

acct_pro_id=[account_profile_id]

Email Snapshot

Email Snapshot will create andstore the HTML and image screenshot of each message sent, including subscriber-specific personalization. If your Realm is enabled for Email Snapshot, to store a copy of each message, set the'snapshot' argument to 1.

Email Snapshot support added in v15.00.00.

snapshot=[0,1]

** Time Zone support, Email Campaign Label support, and Schedule Campaign with Count added in v12.06.0

Question

I noticed the Preference Site I added to our Template does not use a secure link. Is there a way to have it generated on an HTTPS page?

Answer

In order to have the Preference Site served on an HTTPS page, you will need to hard code the URL instead of using the generated tag. Here's how to do that:

Go to Content > Templates

Click on the Template to open it

Select ADD TAGS

Select the appropriate Preference Site from the drop-down

Insert the tag into the Template

On the SaaS, change this: <a href="\%\%PREFSITE\%\%sid=1a:2">Subscribe</a>To:<a href="https://secure.whatcounts.com/ps?id=\%\%SUBSCRIBER_ID_TAG\%\%&sid=1a:2">Subscribe</a>

(Where "1a:2" is the code for your Preference Site.)

In addition to this change to the URL, all assets used in the Preference Site (e.g. images, CSS pages) must be available via HTTPS.

NOTE: The WhatCounts Media Manager does not allow the serving of images or files via HTTPS.

Question

When I place aSubscription form on an HTTPS site, it generates a security error on submit. Is there any way to make that work without the error?

Answer

As long as you are on the SaaS or a Broadcaster that usesan SSL certificate, you can create a Subscription Form that will work on an HTTPS page without generating a security error.

Hereare the changes that need to be made:

In the generated Subscription Form code, change theform "action" to the Secure URL for the SaaS (or Broadcaster):

For the SaaS, change:

<form action="http://whatcounts.com/bin/listctrl" method="POST">

To:

<form action="https://secure.whatcounts.com/bin/listctrl" method="POST">

You must also make sure the landing page is an https page. For example:

<input type="hidden"name="goto" value="https://www.mysecuresite.com" />

If the form action is not changed to a valid secure site or the "goto" value is left as the default (value=""), a Security error will appear.

The HTTP API supports many commands. These commands are case sensitive. The following is a list of all HTTP API commands linked to the related topic:

Command

See Topic

abmailwinner

Choose A/B Winner

acctproaddfield

Create Account Profile Field

acctproaddprofile

Create Account Profile

acctprogetall

Get All Account Profiles

acctprogetfields

Get All Account Profile Fields

acctprogetprofile

Get Account Profile

acctproupdateprofile

Update Account Profile

acctproupdatevalues

Update Account Profile Values

addtolifecyclecampaign

Add Subscriber To Lifecycle Campaign

change

Change Email Address

copyarticle

Copy Article

copylist

Copy List

copytemplate

Copy Template

createarticle

Create Article

createblankarticle

Create Article Blank

createfolderpath

Create Folder

createlist

Create List

createseg

Create Segmentation Rule

createtemplate

Create Template

customfieldcreate

Create Custom Field

customfielddelete

Delete Custom Field

delete

Delete Subscriber

deletearticle

Delete Article

deleteseg

Delete Segmentation Rule

deletesocialproviderbyid

Delete Social Provider by ID

deletesocialproviderbyusername

Delete Social Provider by Username

deletesubid

Delete Subscriber by ID

detail

Show Subscriber Details

excreatelist

Create List

find

Find Subscriber

findinlist

Find Subscriber in List

getabdefinitionbyid

Get A/B Definition

getarticlewithid

Get Article by ID

getarticlewithname

Get Article by Name

getemailcategories

Get Email Categories

getemailphases

Get Email Phases

getemailtypes

Get Email Types

getfillinfields

Get Fillin Fields

getfolderidbypath

Get Folder ID

getlistbyid

Get List by ID

getlistbyname

Get List by Name

getlistcount

Get List Count

getrealmsettings

Get Realm Settings

getsocialpostsfortemplatebyid

Get Social Posts by Template ID

getsocialpostsfortemplatebyname

Get Social Posts by Template Name

getsocialproviderbyid

Get Social Provider by ID

getsocialproviderbyusername

Get Social Provider by Username

getsocialproviders

Get All Social Providers

gettemplatebyid

Get Template by ID

gettemplatebyname

Get Template by Name

gettestcountfordeployment

Get Test Count

launch

Launch Campaign

relationalactivatefield

Activate Field

relationalactivatetable

Activate Table

relationaladdfield

Add Field

relationaladdtable

Add Table

relationaldelete

Delete Data

relationalfind

Find Data

relationalfindfield

Find Field

relationalfindtables

Find Table

relationalsave

Save Data

rpt_abstats

Report A/B Test Statistics

rpt_bounce_stats

Report Bounce Statistics

rpt_browser_info

Report Browser Info

rpt_campaign_list

Report Campaign List

rpt_click_overview

Report Campaign Clicks

rpt_clicked_on

Report Subscriber Clicks

rpt_daily_stats

Report Daily Statistics

rpt_sub_by_update_datetime

Report Subscriber by Update

rpt_subscriber_events

Report Subscriber Events

rpt_subscribers_in_list

Report Subscribers in List

rpt_tracked_events

Report Tracked Events

rpt_tracked_events_by_campaign

Report Tracked Events by Campaign

rpt_unsubscribe

Report Unsubscribes

schedule_deployment

Schedule Campaign Deployment

send

Send One-Off Message

setsocialpostfortemplate

Set Social Post for Template

show_abdefinitions

Show A/B Definitions

show_block

Show Block Bounces

show_calendar

Show Scheduled Events

show_campaign_stats

Show Campaign Statistics

show_campaign_stats_multi

Show Multiple Campaign Statistics

show_campaigns

Show Campaigns

show_complaint

Show Complaints

show_hard

Show Hard Bounces

show_lists

Show Lists

show_opt

Show Optouts

show_optglobal

Show Global Optouts

show_seg

Show Segmentation Rules

show_soft

Show Soft Bounces

show_templates

Show Templates

show_user_events

Show User Events

showarticlelist

Show Articles

springbot_process_abandoned_cart

Process Abandoned Cart

sub

Subscribe

subandsend

Subscribe and Send One-Off Message

templatepreview

Preview Template

testseg

Test Segmentation Rule

unsub

Unsubscribe

update

Update Subscriber

updatearticle

Update Article

updatelist

Update List

updateseg

Update Segmentation Rule

updatetemplate

Update Template

Test List allows you to send a copy of your content to any email addressin order to ensure your message is correctly formatted and no errors exist before deploying a campaign.

Before a template is sent to a subscriber list, it should first be sent to a test recipient or a group of test recipients to check the content and rendering of the template. Test messages can be sent to email addresses that are not subscribed to a specific list. These messages will appear with the same formatting and tracking links as a campaign, but will not collect tracking data or send to subscribers.

While the Test List feature is useful for checking the formatting and layout of your message, not all features of the message will work. FTAF, Display Message, Social, and Preference Management links require an encoded string with campaign details and do not work in Test List messages. To test these links, deploy a campaign with a segmentation rule to select email addresses only.

However, if you click the unsubscribe links, any subscriber associate with the email address sent will be unsubscribed. This is only an issue if you send to recipients who also are subscribed to the selected test list.

To Send a Test Message

Go to TASKS > TEST LIST.

Select aList.

Select a Template.

Select an Account Profile to use when filling the Account Profile tags in your content. The Account Profile defined in the List is selected by default. If no Account Profile tags are defined in your content, you can skip this step.

Enter one or more email addresses as Recipients. Separate multiple addresses with space, comma, or semi-colon. You may use any email address, including those not subscribed to the list. However, if Subscriber or Custom data exists within your Template, it will appear empty for any non-Subscribers.

Select the content Formatsto send: Multipart MIME, Plain Text, HTML.

You may enter an optional string to add to the template subject line by selectingPrepend “Testing” to the subject line. Text defined in the textbox will appear at the beginning of the subject line in the test message.

ClickSend Test.

Each recipient will receive a copy of each format selected. If all three formats are selected, a recipient will receive three messages, one of each type.

The Stop Sending SMS to Subscriber command allows you to unsubscribe an existing SMS subscriber from an SMS Sender Code or create an opt out for any Phone number regardless of subscription. The command is used to remove Subscribers who no longer wish to receive SMS messages or prevent sending to other Phones that are not currently subscribed. The command requires the following arguments: Command, Realm, Password, Phone Number, and Sender Code.

api_web?r=myrealm&p=mypass&c=smsstopsubscribersend&phone=12065551212&sender_code=120162701555

The command is ‘smsstopsubscribersend', the realm is ‘myrealm’ and the password is ‘mypass’. The SMS subscriber with the matching phone number will be removed from the sender code '120162701555'.

Example

Using smsstopsubscribersendwith all commands and arguments (please note the command is wrapped for display purposes only):

api_web?r=myrealm&p=mypass&c=smsstopsubscribersend&phone=12065551212&sender_code=120162701555

Successful results return:

SUCCESS: Stopping message to phone was successful

Results

The Stop Sending SMS to Subscriber command outputs either a SUCCESS or FAILURE message.

Success

The command success message returns the SUCCESS message. The result format is:

SUCCESS: Stopping message to phone was successful

Failure

Thecommand will fail if a subscription does not exist, if the phone number is not found, or if an argument is invalid. The result format is:

FAILURE: [Reason]

Arguments

The command supports the following arguments:

Name

Req?

Description

Argument

Command

Yes

Defines the command to use.

cmd=smsstopsubscribersend

c=smsstopsubscribersend

Realm

Yes

Name of the realm to run the command. This is required, and the command will fail if the realm and password do not match.

realm=[realm_name]

r=[realm_name]

Password

Yes

Authentication code for API access. This is required, and the command will fail if the realm and password do not match.

pwd=[password]

p=[password]

Phone

Yes

Numeric phone number for the subscriber. Do not include special characters (such as parenthesis or dash).

phone=[phone]

Sender Code

Yes

Sender Code representing the message sender. A Sender Code is either a short code or number. It represents the 'from' field when deploying an SMS. The message recipient will see this sender on their mobile device when a message is received.

sender_code=[sender_code]

The HTTP API supports the ability to manage SMS subscriptions and messages, as well as send messages.

Commands

API commands for SMS management include:

Create SMS Message ( createsmsmessage )

Get SMS Messages ( getsmsmessages )

Add Phone to Sender Code ( addphonetosendercode )

Add SMS Subscriber to Sender Code ( addsubscribertosendercode )

Send Message to Phone ( smssendmessagetophone )

Send Message to Sender Code ( smssendmessagetossendercode )

Stop Sending to Subscriber ( smsstopsubscribersend )

Compatible Web Browsers

Chrome: the last 2 major versions

Firefox: the last 2 major versions

Microsoft Edge: the last 2 major versions

Safari: the last 2 minor versions

Browser Add-ons and Extensions

Some browser add-ons and extensions conflict with pop-ups and may block platform functionality. If you are experiencing issues you suspect could be browser related, log out of the platform, clear your browser cache, and log in again. If you've recently installed an add-on or extension, try a different browser or ask a colleague to test on their system. If issues continue, contact our Support team.

Operating Systems

Windows

MacOS

Window Sizes

Minimum experience: >=1000px by >=700px

Ideal Experience: >=1200px by >=700px

On attempt to login, several errors are possible.

Login Error

Issue

The credentials you entered appear to be incorrect.

The User has entered an incorrect login. Verify that the Realm Name, User Email, and Password have been entered correctly, then try again. Five invalid attempts in a short period will result in a lockout, and the User's IP will be prevented from accessing the site until the lockout is cleared. Please contact your Account Manager for assistance.

You don't have the proper permissions to login.

The User permissions are not properly set. To validate the User permissions:

Go to CUSTOMER CARE > USER MANAGEMENT > VIEW USERS.

Click the User to edit settings.

Verify only One Permission option is selected, then click SAVE.

Invalid Temporary IP Authorization Credentials.

The User is attempting to login from an IP that is not authorized in the Temporary Realm security settings. Verify the user is attempting to login from the same IP they requested the Temporary IP.

The IP address from which you are making this request is not allowed to login for the user.

The User is attempting to login from an IP that is not authorized in the Realm security settings. To validate the authorized IP:

Go to CUSTOMER CARE > REALM MANAGEMENT >EDIT REALM.

Scroll down to Security and click Configure IP and Password Settings.

Verify the IP in the IP Restriction list, or enable Temporary IPs, then click SAVE.

Your Realm/Account is inactive

The Realm is not active and will allow no logins. Please contact your Account Manager for assistance.

Login Services Disabled

An excessive number of failed login attempts have occurred and the IP from which the User is attempting to login is temporarily blocked.Please contact your Account Manager for assistance.

Previously used passwords cannot be reused

During Login, if you need to update your password for any reason, you must use a password that has not been used previously. If the password was used in the past, an error will display on login.

The REST API access is restrictedand requiresHTTP Basic Authentication. Authentication requires a Base64 encoded string composedof the Account Name and API Password.

NOTE: API access must be enabled for the Account in order to use the REST API. Please contact your Account Manager if you are unable to access the API Setup.

Basic Authorization

Basic Authorization is required for all API Rest calls. To construct a Basic Authorization header:

Go to CUSTOMER CENTER > API MANAGEMENT > SETUP API.

If using an API Client*, select the client.

Copy the current API Password. If there is no password, click GENERATE PASSWORD.

NOTE:Changing the password invalidates any files using the old password. If the authentication code already exists and you regenerate it, make sure to notify everyone using any of the APIs.

Build a string of the form accountName:apiPassword, for example:

myAccount:xyzpwd123

Base64 encode the string:

bXlBY2NvdW50Onh5enB3ZDEyMw==

Supply an "Authorization" header with content "Basic " followed by the encoded string. Using the example above:

Authorization: Basic bXlBY2NvdW50Onh5enB3ZDEyMw==

API Client Authorization

API Client* Authorization is only required to use an API Client other than the Default associated with the Realm. To construct an API Client X-API-Key:

Go to CUSTOMER CENTER > API MANAGEMENT > SETUP API.

Select an API Client.

If you do not yet have one, click GENERATE AUTHORIZATION CODE.

NOTE:Changing the code invalidates any files using the old code. If the authentication code already exists and you regenerate it, make sure to notify everyone using the selected API Client.

Build a string of the form apiClientName:apiClientAuthCode, for example:

myClient:abcdef123

Base64 encode the string:

bXlDbGllbnQ6YWJjZGVmMTIz

Supply an "x-api-key" header followed by the encoded string. Using the example above:

x-api-key:bXlDbGllbnQ6YWJjZGVmMTIz

* API Client coming in Q1 2020*

The HTTP API interface allows you to send commands to a web based servlet via POST or GET. All HTTP API commands are handled through api_web. The fully qualified URL is:

http://[siteurl]/bin/api_web

where 'siteurl' is the URL you use to access the API for your system. If you are on the Professional Edition SaaS, the URL would be:

http://api.whatcounts.net/bin/api_web

You can submit data to the servlet via POST or GET. Testing with a browser is performed through GET. To handle any significant amount of data, you must run the command through POST. If you test through your browser, you will likely reach a limit of 1,000 characters, a limitation of GET. POST has no predefined limit.

The HTTP API takes several arguments, three of which are always required. Please note the case of each argument in documentation, as the api is case sensitive.

Name

Description

Argument

Command

The command tells the API what task to perform.

cmd=[command]

c=[command]

Realm

Authentication is based on realm and password. The realm name is determined when your account is created, and can be seen in the Welcome message you receive with your platform login credentials. The realm must be defined first.

realm= [realm_name]

r=[realm_name]

Password

The password, also known as an authentication code, must be defined after the realm.

pwd=[password]

p=[password]

password=[password]

API Client*

Client authentication provides another level of user access and security. This is optional instead of using the Default API Client.

API Client is available tobetter manage clients' access and usage of APIs.Each realm has a default API Client which requires only the Realm and Password above. When using one of the four possible API Clients, the API Client Name and Client Authentication must also be included in the header.

To define an API Client,login to the platform and then go to CUSTOMER CENTER > API MANAGEMENT > SETUP API. You must generate the Authorization Code, then generate the API Password

If using an API client, define it after the password.

**Added in v15.02**

api_client=[client_name]

API Client Authorization

Changing the API Client Authorization code invalidates any files using the old code. If the authorization code already exists and you regenerate it, make sure to notify everyone using the API Client in any of the APIs. This is required when using any API Client other than Default.

client_auth=[client_auth]

Data Fields

The Data argument requires additional fields to identify individual subscribers or email recipients. For example, with a Subscribe command, the data argument represents a Subscriber to import and subscribe to a list. Each data argument requires fields to identify a subscriber, such as email and first.All date fields require a 2 digit month, 2 digit date, and four digit year, such as 03/27/2019, 2019-03-27.

The Subscriber Data fields include:

email

address_1

state

phone

first

address_2

zip

fax

last

city

country

company

Four additional Subscriber Data fields are used for special values:

duplicate

To force duplicates, a unique first name must be identified, and the duplicate field must be set to 1.

format_number

To specify the format of the email messages your subscriber will receive, you can set the format_number in the Data fields instead of as an argument.

1 = plain text (DEFAULT)

2 = HTML

99 = Multi-part MIME

format_text

To specify the format of the email messages your subscriber will receive, you can set the format_text in the Data fields instead of as an argument.

plain = plain text (DEFAULT)

HTML = HTML

mime = Multi-part MIME

multi = Multi-part MIME

customer_key

Subscriber's unique identification string. Only available on some systems. This field is required when enabled in the realm settings.

Custom Fields

Custom fields can be specified by appending the string “custom_” to the field name. For example, if your realm has a custom field named “age”, specify it as a data field using “custom_age”. If you are attempting to import custom data and the data remains blank in the database, check that the custom field has been properly identified in the data file preceded by “custom_”.

Please note that custom fields are case sensitive and long names or names with spaces are prone to error.All date fields require a 2 digit month, 2 digit date, and four digit year, such as 03/27/2019, 2019-03-27.

Separators and Delimiters

Commands that require a list of data use a separator between the data definition and the data values, as well as a delimiter between each data value. The default separator and delimiter are acceptable for most use cases, especially when the data values have been enclosed in double quotes, however there are instances where one or both of the characters occur in a data value, and therefore must be redefined.

For example, the following subscribe command uses the default separator (^) and delimiter (,) with no issues:

api_web?c=sub&r=myrealm&p=mypass&list_id=5&data=email,first,last,custom_special^[email protected],Jane,Doe,special+text

However, the following subscribe command uses the default separator (^) and delimiter (,) and the data values also contain the same characters:

api_web?c=sub&r=myrealm&p=mypass&list_id=5&data=email,first,last,custom_special^[email protected],Jane,Doe,special^text1,special^text2

In the second example, the custom_special field contains both a caret and a comma. The caret causes the parser to think there is another row of subscriber data to import. If there were no caret, the comma would cause the parser to think that an extra Data Field was required. The two solutions for this issue are either double-quoting the data values and/or custom defining the separator and delimiter in the command. For example:

api_web?c=sub&r=myrealm&p=mypass&list_id=5&data=email,first,last,custom_special^"[email protected]","Jane","Doe","special^text1,special^text2"

OR

api_web?c=sub&r=myrealm&p=mypass&list_id=5&separator=~&delimiter=|&data=email,first,last,custom_special^[email protected]|Jane|Doe|special^text1,special^text2

You may find that in most cases you will not need to define either separator or delimiter, and in some instances you may need only one or the other.

Avoid using the following characters, as they are already in use in the commands:

Character

HEX

space

\%20

ampersand

&

\%26

plus

+

\%2B

comma

,

\%2C

forward slash

/

\%2F

quote

'

\%27

double quote

"

\%22

caret

^

\%5E

question

?

\%3F

underscore

_

\%5F

equals

=

\%3D

percent

\%

\%25

Suggested substitutions include:

Character

HEX

line feed

\%0A

carriage return

\%0D

tilde

~

\%7E

pipe

|

\%7C

Return Values

Most commands return SUCCESS and descriptive information if the operation is successful or FAILURE and a reason if the operation fails. The default output for other results is a single, wrapped line of text separated by spaces. You can specify the format you would like output and include column headers, or labels, for CSV results.

To change the returned format, use one of the following arguments in your command:

Argument

Description

&csv=1

Return quoted, comma separated values (CSV) output.

&output_format=csv

Return quoted, comma separated values (CSV) output.

&output_format=csv_pipe

Return quoted CSV output, but separate fields using the pipe (|) character.

&output_format=csv_tab

Return quoted CSV output, but separate fields using the tab (\t) character.

&output_format=xml

Return XML output.

&headers=1

Include headers for the CSV output.

Special Characters

Since the HTTP API commands can be used through a browser, you may need to replace some special characters with URL friendly versions. For example, use of the carrot (^) character to represent a new line. In addition, you can use the return (\r) and newline (\n) variations to represent line breaks.

When sending data that contains a space character through a browser, be sure to use the plus (+) character or URL Encoded space (\%20) to replace the space.

Other characters you may find you need to replace include the following:

Character

HEX

space

\%20

ampersand

&

\%26

plus

+

\%2B

comma

,

\%2C

period

.

\%2E

forward slash

/

\%2F

colon

:

\%3A

semi-colon

;

\%3B

less than

<

\%3C

greater than

>

\%3E

question

?

\%3F

As an exception, the double quote character (") must be escaped using the backslash (\). For instance, the text:

This sentence contains "quoted" text

Would be escaped as:

"This sentence contains \"quoted\" text"

Where each double quote is preceded by a backslash, and the entire data string is enclosed in quotation marks. If you do not quote the entire string, the command may fail. The escaped quotes will be ignored and the string may be improperly stored as:

This sentence contains \quoted" text

The HTTP API is commonly used through another programming language or environment, such as PHP or Python. The benefit is that it can be used by any code that can issue and process HTTP GET or POST transactions.

Java Example

The following is a simple example in Java:

// Display lists public static

String showLists () {

// cmd = show_lists

// realm = sample

// pwd = trelMark9

// csv = 1 so we’ll get CSV output

String cmd = “api.whatcounts.net?cmd=show_lists” + “&r=myrealm&pwd=mypass&csv=1”;

// perform an HTTP GET for the data

String results = httpGET (cmd);

// display our results

System.out.println (results); }

// Perform an HTTP get for URL public static

String httpGET (String command) {

String rc = "";

if (!command.toLowerCase ().startsWith ("http://"))

command = "http://" + command;

try

{

URL url = new URL (command);

URLConnection conn = url.openConnection ();

conn.setDoInput (true);

conn.setUseCaches (false);

InputStream is = conn.getInputStream ();

BufferedReader d = new BufferedReader(new InputStreamReader(is));

String line = "";

while ((line = d.readLine ()) != null)

rc += line + "\n";

d.close ();

is.close ();

}

catch (Exception e)

{

}

return rc; }

An alternate Command example using one of the four possible, non-default API Clients* for a realm:

String cmd = “api.whatcounts.net?cmd=show_lists” + “&r=myrealm&pwd=mypassalt&api_client=myClient&client_auth=clientauth&csv=1”;

* API Client coming in Q1 2020*

The Get Templates commands allow you to return the content of a template specified by ID or name. This command returns the template id, name, subject line, Plain Text body, and HTML body of each template.

Arguments

The Get Template commands require the following arguments: Command, Realm, Password, and either Template name or Template ID.

api_web?r=myrealm&p=mypass&c=gettemplatebyid&template_id=42

The command is ‘gettemplatebyid’, the realm is ‘myrealm’, the password is ‘mypass’, and the ID is '42'.

api_web?r=myrealm&p=mypass&c=gettemplatebyname&template_name=mytemplate

The command is ‘gettemplatebyname’, the realm is ‘myrealm’, the password is ‘mypass’, and the name is 'mytemplate'.

The Get Template commands support the following arguments:

Name

Req?

Description

Argument

Command

Yes

Defines the command to use.

cmd=[gettemplatebyid, gettemplatebyname]

c=[gettemplatebyid, gettemplatebyname]

Realm

Yes

Name of the realm to run the command. This is required, and the command will fail if the realm and password do not match.

realm= [realm_name]

r=[realm_name]

Password

Yes

Authentication code for API access. This is required, and the command will fail if the realm and password do not match.

pwd=[password]

p=[password]

Version

Version of API to use. Data may be added to newer versions of the API. To alleviate issues for users who have already coded file parsing, new columns are only displayed if the version is included.

version=[version_number]

8.4.0 = folder_id

Template Identification

Yes

Name or ID of the template to return. If there are spaces in the name, you can replace the space with + or \%20 to avoid possible issues with spaces in a URL.

template_name=[template_name]

or

template_id=[template_id]

Output Format

To specify the format of the list output, use one of two arguments. If no argument is included, the default output is space-delimited plain text string, which may not include all data columns.

csv=1 or

output_format=[csv,csv_tab, csv_pipe,xml]

Header

To define the data with a label, use the Header argument. This can only be used in conjunction with the output format, and does not affect XML.

headers=[0,1]

DEFAULT==0

Example

Using all commands and arguments (please note the command is wrapped for display purposes only):

api_web?r=myrealm&p=mypass&c=gettemplatebyid&template_id=42&output_format=csv&headers=1&version=8.4.0

Successful results return:

"Template ID","Template Name","Template Subject","Body Plain","Body HTML","Template Description","Folder ID" "42","mytemplate","My Subject Line","this is a Plain test","this is an HTML test","","2"

If not output format is defined, plain results return:

"Template ID","Template Name" "42","mytemplate"

Results

The Get Template commands output either the results of the search or a FAILURE message.

SUCCESS

The Get Template commands do not explicitly return a Success code. Instead, it outputs the template data. Use the Output Format argument to return the results in a specific format.

FAILURE

A Get Template command will fail for several reasons. The result format is:

FAILURE: [Reason]

Overview

The Subscription Form Wizard makes it easy to create forms and links that allow your subscribers to join lists or opt out. While the Wizard only allows you to create a form to sign up to a single list, you can modify it to create a form that accepts multiple list signups at one time.

Modifying the Form

Use the Subscription Form Wizard to create a Subscription Form for one of your Lists. The part that is unique for each List is the SLID (Special List ID). You can find the SLIDs for the rest of the Lists you would like included in your form using the List Matrix.

To start:

Go to SUBSCRIBERS > SUBSCRIPTION FORM WIZARD

From the 'Lists' drop-down, select one of the Lists you want in your form.

From the Generate drop-down, choose "Subscribe Form"

Click NEXT.

Select any Subscriber and/or Custom Data you would like included in your form.

Click NEXT.

The resulting HTML will be similar to the following:

<form action="http://whatcounts.com/bin/listctrl" method="POST">

<input type=hidden name="slid" value="123ABC456DEF" />

<input type=hidden name="cmd" value="subscribe" />

<input type=hidden name="goto" value="" />

<table>

<tr>

<td style="text-align:right;">Email:</td>

<td><input type="text" id="email" name="email" size="25" /></td>

</tr>

<tr>

<td> </td>

<td><input type="hidden" id="format_mime" name="format" value="mime" />

<input type="button" value="Cancel" />

<input type="submit" value="Subscribe" /></td>

</tr>

</table>

</form>

Paste the HTML into a text editor

Next, go to LISTS > LISTS

SelectTHE LIST MATRIX button

From 'Format' choose CSV then click CREATE.

Open the file that is generated and look for the 'List SLID' values for the other Lists you want included in your form

Go back to theHTML in your text editor

Notice the second line of code in the form where name="slid". Cut out that line, and make a copy of it foreach List like the following:

<input type=checkbox name="slid_[#]" value="[SLID]">[List Name]

For example:

<input type=checkbox name="slid_1" value="123ABC456DEF">Monthly Newsletter<br />

<input type=checkbox name="slid_2" value="789GHI012JKL">Product Updates<br />

<input type=checkbox name="slid_3" value="345MNO678PQR">Service Bulletins<br />

Add the following line of code inside the form just before the table. This is required to allow for multiple list selections in the form:

<input type="hidden" name="multiadd" value="1" />

Remove the hidden SLID field at the top of the form:

Save the .html file and test your form. The form will be similar to the following:

<form action="http://whatcounts.com/bin/listctrl" method="POST">

<input type="hidden" name="slid" value="123ABC456DEF" />

<input type="hidden" name="cmd" value="subscribe" />

<input type="hidden" name="multiadd" value="1" />

<input type="hidden" name="goto" value="" />

<table>

<table>

<tr>

<td style="text-align:right;">Email:</td>

<td><input type="text" id="email" name="email" size="25" /></td>

</tr>

<tr>

<td> </td>

<td>

<input type=checkbox name="slid_1" value="123ABC456DEF">Monthly Newsletter<br />

<input type=checkbox name="slid_2" value="789GHI012JKL">Product Updates<br />

<input type=checkbox name="slid_3" value="345MNO678PQR">Service Bulletins<br />

</td>

</tr>

<td> </td>

<td><input type="hidden" id="format_mime" name="format" value="mime" />

<input type="button" value="Cancel" />

<input type="submit" value="Subscribe" /></td>

</tr>

</table>

</form>

Notes

If you are on a Broadcaster, change the "form action" to the URL appropriate for that system.

Testing

Be sure to test your form once you have saved it. When the form is submitted, that email address will be subscribed to any Lists where the checkbox was selected. Use the Subscriber Search feature to find the record for the email address you subscribed, and ensure it reflects the Lists you selected to join. If a Global Opt Out record exists for the Subscriber, no subscriptions will be added.

The Subscription Form honors all Double Opt In and Courtesy options set in the List properties. The Subscriber will receive an individual Confirmation and Courtesy message for anyList with those options enabled.

Once you have confirmed your form is functional, it can be incorporated into the code onyour website.

The HTTP API supports the use of Folders to organize Lists, Templates, Articles, and Segmentation Rules. Several HTTP API commands accept or require a folder_id to process. You can view these IDs by using the Get Folder ID command.

Commands

API Commands for Folder management include:

Create Folder Path (createfolderpath)

Get Folder ID (getfolderidbypath)

The HTTP API supports the ability to Publish directly to Social Networks. Several HTTP API commands accept or require a template_id to process. You can view these IDs by using the Show Templates command, or create a new template and return its ID.

Commands

API Commands for publishing to Social Networks include:

Get All Social Providers (getsocialproviders)

Get Social Provider by ID (getsocialproviderbyid)

Get Social Provider by Username (getsocialproviderbyusername)

(deletesocialproviderbyid)

Delete Social Provider by Username (deletesocialproviderbyusername)

Set Social Post for Template (setsocialpostfortemplate)

Get Social Posts for Template by ID (getsocialpostsfortemplatebyid)

Get Social Posts for Template by Name (getsocialpostsfortemplatebyname)

When using a subscribe or unsubscribe forms, it is possible to pass values entered in those forms to landing pages. This allows for the creation of features like progressive subscribe forms. This is accomplished by creating a form using the Subscription Form Wizard, defining a Landing Page, and then editng the HTML to add the hidden goto_pass_along input field(s) to the form.

The goto_pass_alongfield tells the listctrlprogram which fields to append to the landing (goto) page. The goto_pass_along_aliasescode allows you to use your own names in case the form field names don't suit your application.

To define which fields append to your landing page URL, enter one or more field names as the value for the goto_pass_along form field. Separate multiple entries by commas or semicolons. The fields you pass along will be visible in the address bar of the subscriber's browser. To if you would like the field name shown in the address bar to be different than what it is in the platform, add a hidden goto_pass_along_aliases input to your form. If goto_pass_along_aliases is used, each value in the goto_pass_along input must have a corresponding value in goto_pass_along_aliases.

In the example below, the hidden goto fields appear in red. The goto_pass_alongcode identifies the fields emailand custom_favorite_flavorto use. The optional goto_pass_along_aliasesstipulates that when these fields are appended they use the namesemailandflavor.

<form action="http://whatcounts.com/bin/listctrl" method="post">

<input type=hidden name="slid" value="10888353310">

<input type=hidden name="cmd" value="subscribe">

<input type=hidden name="format" value="plain">

<input type=hidden name="goto" value="http://whatcounts.com/bin/hello">

<input type=hidden name="goto_pass_along" value="email,custom_favorite_flavor"&gt

<input type=hidden name="goto_pass_along_aliases" value="email,flavor">

Email:<input type=text name=email size=12>

Favorite flavor: <input type=text name="custom_favorite_flavor" size=15>

<input type=submit value="Subscribe">

</form>

The GOTO url in this form is the dynamic landing page, the fieldsemailandcustom_favorite_flavor will be appended to the URL. If you had entered [email protected] values into the form, upon submission you would be redirected to the URL:

http://whatcounts.com/bin/[email protected]&flavor=Strawberry

Question

When submitting a WhatCounts subscription form, why is the following error displayed:

"Unknown User We were unable to locate an entry for you in our database and, therefore, were not able to complete your request. In case it's a result of a technical problem on our side, we've generated and sent a message to our customer support team. Thank you and please accept our apologies if this caused you any inconvenience."

Answer

An Unknown User error may occur for any of the following reasons:

Email address was not entered before the form was submitted

Email field is missing from the form

Email field is using the incorrect form field name

To resolve the issue, verify the Email field exists and is in the following format:

<input type="text" id="email" name="email" size="25" />

Although the 'type' and 'size' items in the input can be adjusted, the name of the field input must be "email" in all lower case letters. If all upper case or title case is used, the system will not understand the input andan "Unknown User" error will be displayed.

Question

How do I populate the State form selection list in my Preference Site with the State names?

Answer

When you insert the State Form Selection List it will initially be empty. You can automatically populate the selection list by adding code to the page. The pref_site.js is required for this to work and is included by default when you create a page.

To populate the selection list, you must add a line of code in the <script> portion of the HTML Head. Below the init(); line in the $(document).ready() function, add:

populateStates('state', 'Select a State');

To make the function appear as:

$(document).ready(function() {

init();

populateStates('state', 'Select a State');

});

The first parameter in the command is the <select> id, and the second parameter is the default item that will appear at the top of the list. You can change the word 'Select a State' to your own label, such as 'Choose Your State'.

To display the State the subscriber has already selected, change 'Select a State' to '${state}'. If the subscriber has no State set, then the option will appear blank by default followed by the additional options to select.

Question

How do I add the Captcha feature to existing subscription forms?

Answer

If you currently are not using the Captcha feature, you will need to contact Technical Support to enable this feature. However, once enabled all subscription forms must use Captcha. Therefore it's best to alter your subscription forms first. A form that contains Captcha fields will function, ignoring the Captcha but otherwise working so you can add those fields prior to requesting enabling of option.

When enabled, the Subscription Form Wizard will include this HTML code. Thus these are the fields that are needed for Captcha to function. Formatting can be changed to suit your existing page.

<tr>

<td style="text-align:right;">Verification:</td>

<td>

(Enter number in image)

<input type="text" name="verification" size="8" maxlength="8" autocomplete="off" />

<img src="http://whatcounts.com/bin/icon_generator?key=captcha-key" border="0" />

<input type="hidden" name="key" value="captcha-key" />

<input type="hidden" name="captcha_failure_to" value="" />

<input type="hidden" name="captcha_max_retries_to" value="" />

</td>

</tr>

(Note: this is for SaaS customers. Broadcaster customers will need to revise the <img> tag src domain to match.)

The "captcha_failure_to" value is a URL to a landing page if an incorrect Captcha entry is made the first two attempts.

The "captcha_max_retries_to" value is a URL to a landing page if an incorrect Captcha entry is made after three attempts.

If these these two fields are left empty, a default page will be displayed.

Question

What happens if a subscription form does not include Captcha fields when the option is enabled?

Answer

The Captcha option requires Captcha fields to be part of any subscription form. If a realm has this option enabled, any subscription forms must include the Captcha fields to function. A subscription form without those fields will always result in an error message indicating that the text entered did not match the image. (Captcha image)

Overview

Users with Super Admin or Private Label Admin permissions can create a new Realm.

To create a new Realm

Go to the Customer Menu, thenREALM MANAGEMENT > CREATE REALM.

Enter a Realm Name.

Enter a Description.

If this is a child realm, select the Parent Code.

Choose the appropriate option from the WhatCounts db profiles drop-down

Make any other selections, then click CREATE.

Question

How do I create a Segmentation Rule to pull only the subscribers who opened 90 days ago, but have not opened since?

Answer

The following example uses Standard Segmentation to target the Subscribers who opened an email 90 days ago, but have not opened since. This Segmentation Rule could easily be modified to match other tracking events, or a different time period.

It is important to note that this Segmentation Rule will pull Subscribers with an open from an Campaign in the realm -- not just those from the same List the Segmentation Rule is being applied against.

Here's how to set up this Segmentation Rule:

Go to Segmentation > Create Standard Rule

Enter a Name.

Create the first condition that will allow for the necessary nesting of the others:

In the Search Fields option in the left navigation enter: email

Drag Email Address on to the workspace

From the drop-down, select: Is not Null

Create the condition for: tracking event 90 days ago

In the Search Fields option enter: tracking

Drag Tracking Event Date on top of the Email Address condition

From the drop-down, select: Days Before

Click in the field next to the calendar icon and select: Today

In the next drop-down, select: Equals

In the final field, enter: 90

Create the condition for: opened

Drag Tracking Event Type on top of Tracking Event Date condition

From the first drop-down, select: Equals

From the next drop-down, select: Open Message

Change the operator between the Event Date and Event Type conditions to: AND

Change the operator between the Email and nested Event Type conditions to: AND

Create the condition for: tracking event within the last 90 days

Drag another Tracking Event Date from the left navigation into the nested section with the other Tracking conditions where 'Drop Condition here' appears

From the drop-down, select: Days Before

In the field next to the calendar icon select: Today

In the next drop-down, select: Less than

In the final field, enter: 90

Create the condition for: opened

Drag another Tracking Event Type from the left navigation into the nested section with the other Tracking conditions where 'Drop Condition here' appears

From the first drop-down, select: Equals

From the next drop-down, select: Open Message

Change the operator between the Event Date and Event Type conditions to: AND

Nest each Tracking Event Type and Tracking Event Date pair by dragging a Tracking Event Date Condition onto a Tracking Event Type and releasing when Nest Condition appears

Change the operator between the 'open 90 days ago' and'open within the last 90 days' to NOT

This rule will now pull all Subscribers with an open EXACTLY 90 days ago but NOT in the days since.

The final rule should look like this:

List Attributes Tags are used to output custom details about the List to the content. These tags are filled after a campaign is created, though can also be viewed in Template Preview by entering a Subscriber Email address and selecting a List. For more details, see List Attributes Tab.

List Attribute Tags in Content

List Attributestags are built by adding the 'em_list_' in front of the ListAttribute name to create the email list tag. For example, to pull an attribute named salesperson into a template, use thetag: \%\%$em_list_salesperson\%\%.

Only those attributes that contain a Value defined in the List Properties, Attributes tab will fill in your content. For example, you have definedthree attributes in your Lists: version, frequency, source.

The tags for these attributes are: \%\%$em_list_version\%\%, \%\%$em_list_frequency\%\%, \%\%$em_list_source\%\%.

However, in your List, you have only set the value for frequency: Monthly. When you deploy your campaign, only the tag for\%\%$em_list_frequency\%\% will be defined.

*Feature introduced in v11.10.

List Attributes allow you to define values in a list that can be pulled into a template. This providesthe ability to set values associated with the list and use them to customize your message.

The system supports up to fifty*List Attributes. List attributes are shared by all lists in the Realm. However, the value is specific to each list. This means that the value of em_list_salespersonmaybe Tom Smith in List A, but Sally Jonesin List B.

Only those attributes that contain a Value will fill in your content based on the List deployed and the tag(s) defined in the content. For example, you have definedthree attributes in your Lists: version, frequency, source. The tags for these attributes are: \%\%$em_list_version\%\%, \%\%$em_list_frequency\%\%, \%\%$em_list_source\%\%. However, in your List, you have only set the value for frequency: Monthly. When you deploy your campaign, only the tag for\%\%$em_list_frequency\%\% will be defined.

List Attributes can be defined and set for both Lists and List Definitions. When creating a new List from a List Definition, the List will inherit the Attributes defined in the List Definition. In addition, creating a copy of a List or List Definition will create an exact copy, including all defined Attributes.

List Attributes do not support the use of Template Tags as the value. However, you may saveHTML for each Attribute, including Image and URL HTML tags. HTML can only be saved for an Attribute that has already been defined. You cannot enter HTML into a Value field when you create a new Attribute.

An example use of List Attributes is tosupport your various Newsletters. If you have separate Lists for each newsletter, you may create attributesto define the Newsletter name, frequency, logo image, and URL to a related site. If you have three newsletters, you can send campaigns which use the same template, such as a generic Welcome message, but insertnewsletter specific details based on the targeted List using the List Attribute Tags.

See List Attribute Tags for more information on using the tags in your content.

To View List Attributes

Go to Lists > Lists and click on any list or go to List > List Definitions and click any definition.

Clickthe Attributes tab.

NOTE: The options to Cancel, Delete, or Save a list are not available from the Attributestab. When you click ADD,SAVE, or DELETE in List Attributes, any changes that were made in other List Properties tabs will be lost. Be sure to save any changes to List Properties before adding or editing List Attributes.

To Create an Attribute

Enter a unique name in the Attributefield. The name cannot contain spaces or special characters other than underscore (_).

Define acorresponding value in the Valuefield. This value will only be used in campaigns deployed from this specific list.

NOTE: For security reasons, HTML cannot be stored in the Value field at time of creation. Instead, you must Add the new Attribute with a blank value, then edit the Attribute to add the HTML to the Value.

ClickAdd.

Once created, theList Attribute name is prepended with the email list tag identifier"em_list_" and the name is stored in all lower case characters. If you create an attribute namedSalesperson, the AttributeTagisem_list_salesperson.

To Edit an Attribute

To edit an AttributeValue, change the text in the value box and click the Save link to the right ofthe Attribute. An Attribute Name cannot be edited.

To Delete an Attribute

To remove an Attribute, click the Deletelinkto the right of the Attribute. This will remove the Attribute from all lists in the Realm. You will receive no warning notification. All Templates or Articles that contain Tags for the deleted Attribute should be edited to remove references to the Tag.

*Feature introduced in v11.10.

*Updated to allow up to 50 Attributes in v12.03.

Question

How do I include alternate text for subscribers who do not have a first name?

Answer

To print the subscriber's name if it exists, or alternate text if it doesn't, use the following:

Dear \%\%if first != "" then printdata first else print "Valued Customer"\%\%,

This will check if the first name field is filled for each subscriber. If the first name exists, it will be printed. If it is blank, the text "Valued Customer" will be printed.

14.16.00 - 09/05/2019

v14.16 resolves issues, provides UI improvements, and prepares for continued UI updates.

New Features

None

Improvements

FTP API: SmartSubscribe add default format (plain text) if none defined

Bugs

A/B Test: Sends notifications to Admin Email from List Properties instead of admin_email in system config

FTP API: Do not clear data with BLANK submitted via sub, save, send, subandsend

HTTP API:

SMS call to update subscriber with invalid country code returns incorrect error message

Subscriber Data fields are not updated with UPDATE command

Subscriber Data fields are not updated with SUB command

Automation Definition: On Close, returns to list of Campaigns instead of Definitions

Automation Campaign:

When Copying, Campaign Title should be required

On Close, returns to old UI list of Campaigns

In Create modal, list definitions by Title not Name

Typo in Activate Modal - "Active" should be "Activate"

Import: Non-smartsubscribe import handles NULL differently

Deliverability: Authentication failures with ReturnPath

Realm Create:

Do not use Parent VMTA if Parent does not have share enabled

Do not clear fields if error on submit

Campaign: Archive viewer min=n number not showing correct content

Current Tasks: Time is sorted incorrectly

14.15.00 - 08/22/2019

v14.15 resolves issues, provides UI improvements, and prepares for continued UI updates. Automation Definitions and Automation Campaigns pages have been updated to the new UI.

New Features

Automation Campaigns: Update to new UI

Automation Definitions: Update to new UI

Improvements

Publishing: Improvements

Bounce Tracking: Improved data storage and logging

Bugs

Webservices API: userUnsubscribeUpdateData does not save Date custom field correctly

WhatCounts Logo: Does not direct to new Dashboard

Create Realm: Hide Client field when creating a child realm

Notifications

Create User: Email Notification "go to" url incorrect

Forgot Password: Email Notification "go to" url incorrect

Publishing: Get default VMTA from parent first

PLA: Cannot create new realm

14.15.01 - 08/22/2019

Bugs

Publishing improvement when Segmentation has 0 subscribers

Tracking improvement for data storage

14.15.02 - 08/27/2019

Bugs

Campaign: not using VMTA set at List Properties level

14.13.00 - 07/25/2019

v14.13 resolves issues, provides UI improvements for several of the newer pages, and prepares for continued UI updates. A new feature is available as a fee based service to store an image and HTML copy of each message sent to each subscriber.

New Features

Publishing: APIs can use a specific VMTA for transactional (one-off) sends

Email Snapshot: Store an image and HTML copy of each message sent to a subscriber (Fee based service)

Improvements

FTP API: SmartSubscribe add default format (1) if none specified

Throttling

Add indication that task is throttled Publishing Control

Add indication that task is throttled in Current Tasks page

Realm Creation: Database selection no longer optional

Reporting Overview Pages: Do not automatically close Export results banner

Publishing: Improved performance and logging

Scheduled Tasks:Improved performance and logging

Ecommerce: Increase timeout values

Bugs

Batch Subscribe: Does not honor Seed List limit

Calendar:

Task does not appear if current day for Realm Timezone does not match database Day

Scheduled Campaigns first of month show up incorrectly in Calendar page depending on timezone

API Overview:

Labels search does not work

Align Sent number

Deployed Overview: Column sorts are broken

Automation Overview: Graph shows data, but table is returning no data, after using Labels filter

Campaign Details:

Labels are not displayed as expected

A/B Campaign: Heat map does not display correctly for winning campaign

Users: Adjust Name and Email column widths

Super List: Missing details that it "does not dedupe when workflow is enabled"

Subscriber Search:Does not find Exact Match with all fields

Template Editor: "Generate Tag" button for relational table content loads blank screen

Documentation

API HTTP: Update FIND to clarify how it works in a Customer Key realm

Find Subscriber

Find Subscriber in List

Each subscriber opt out is tracked with the source from which it is generated. The following opt out sources and IDs are used in several reports:

Source

ID

Description

MANUAL_OPTOUT

0

Subscriber opt out as a reply sent to bounce mailbox

ADMIN_OPTOUT

1

Admin opt out via user interface

EMAIL_HARDBOUNCE

10

Hard bounce to bounce handler

EMAIL_CONFIRMATION

11

Subscriber opt out via an e-mail confirmation handled through confirmation tool. This has been deprecated because Opt Out confirmation is no longer supported due to the CAN-SPAM Act.

EMAIL_UNSUBSCRIBE

12

Subscriber opt out out via an e-mail unsubscribe request handled through special bounce mailbox

FBL_COMPLAINT

13

ISP Feedback Loop Complaint opt out

EMAIL_ADMIN_UNSUB

14

Admin unsubscribe via email admin feature

FTP_OPTOUT

20

Subscriber or Admin opt out via FTP file upload

SUPPRESSION_LIST

21

Admin opt out via suppression list

OPTOUT_SUBSCRIBERS

22

Admin opt out via Opt Out Wizard (new in v8.3.4)

WEB_API_OPTOUT

30

Subscriber or Admin opt out via the api_web servlet web based API

WEB_CONFIRMATION

31

Subscriber click unsubscribe link in email

WEB_PROFILE_MGMT

32

Subscriber opt out via Profile Management page

UNSUB_CENTRAL

34

Admin opt out via UnsubCentral data pull

PREF_SITE

35

Subscriber opt out via Preferences Unsubscribe/Manage Site (new in v8.5.0)

LIFECYCLE

40

Subscriber opt out via Automation Campaign

UNKNOWN

100

Unknown source for the optout

14.14.00 - 08/08/2019

v14.14 resolves issues, provides UI improvements, and prepares for continued UI updates. Automation Overview and SMS Overview pages have been updated to the new UI.

Finally,support for the Groups permissions option has been removed. It has not been supported through most of the UI for some time, and we have deprecated the feature from the remaining locations.

New Features

Automation Overview: Update to new UI

SMS Overview: Update to new UI

Improvements

Task History: Add flag indicating Published List was de-duped on send (see List Properties, Advanced Tab )

Realm Create/Edit: Add VMTA requirement validation to Create/Edit Realm pages. VMTA settings were previously optional.

Bugs

Announcements: Not appearing on glider pages

Templates: Copy Template does not validate OWASP string

Deliverability: 250OK campaigns not showing up in UI

REST API: Create Subscriber on Customer Key realm fails

Automation Campaign: Retain Active Loss In data for Archived campaigns

SMS Overview: Bounced events not included in graph

Documentation

About Realm : Update VMTA info

Realm Settings : Update with new options

Deprecation

Groups

When you create or edit a Realm, several settings affect how you mayuse the available features. The available Realm Settings are as follows:

Account Realm

Realm Name: Name of the Realm, 12 characters or less, no spaces or special characters. Do not end with a top level domain like ".com" as that could cause problems with some platform functionality. Available to Private Label Admins.

Description: Short description of the realm.Available to Private Label Admins.

Parent code: Select the name of the Parent Realm if this is a child

Quiesced: Take the realm offline, do not update data from logs or include in scanning

Active: Select to make this Realm active and usable.Available to Private Label Admins.

Client:Account (WhatCounts Client) to associate all related billing and data reporting. (new in v14.14)

OSG Client:Realm is also an OSG client or client of an OSG subsidiary (new in 13.03)

Billing Status:Realm is billed directly by Whatcounts. Enabled by default (new in 13.03 )

Client Type: Set to Marketing by default(new in 13.03 )

Realm Code: Encoded string generated upon Realm creation.

Database Server: Select Database to create new Realm.Previously allowed as Database Profile

Customer Key: Add unique identifier for subscriber records

Customer Key Approval: Email address of the WhatCounts Employee who approved use of Customer Key for the realm.

Date/Time Storage: Enable Millisecond Precision when storing Date/Time in the database. Do not enable for realms with MySQL prior to 5.6.4 and MySQL databases that have not been modified to support millisecond precision.

OEM Features:

Customer is OEM: Select to allow customized Login URL and Images in order to resell features to third-party users.

Login URL: Enter a fully qualified customURL to access the system, e.g.https://oem.mydomain.com.

Login Page, Small Image URL: URL to the small logo image displayed on the Login page above the required Login fields. The image willresizeto display at height of 70 pixels.

Login Page, Left Side Image URL: URL to the large image displayed on the Login page tothe left of the Login fields. The image will resize to the height of the browser space.

Header Image URL: URL to the smallheader image displayed in the upper, left-hand corner of the site after login.The image willresizeto display at height of 40 pixels.

Child Realms: Select to enable this Realm as a parent realm and allow it to have child realms. Set 'Base realm name' to identify the child realms. All child realm names will be prefixed with this value plus an underscore (ie: parent_child).

Timezone: Select the local timezone for data reporting

LayoutPalette: Configure color settings for use when editing Creative Library Layouts. When a realm is created, the default HEX values are set. Edit the HEX values using the format #xxx or #xxxxxx, the 3 or 6 digit HEX value for the color you wish to use. (new in v11.3.0)

Automation Actions:Days until Waiting Actions are purged from inactive Automation Campaigns. Enter a value from 1 to 30 days, default is 14 days. (new in v11.15.0)

Demo status: Select to designate the realm for Demo purposes only, such as for prospective clients, and indicate a limit for the maximum number of subscribers allowed in the Realm.Available to Private Label Admins.

File Upload Size Limit: Limit the size of files allowed to upload to the Media Manager. Default is 300k. (new in 13.00.0)

Media Bandwidth Size Limit: (new in 13.00.0)

Use New Sticky: not in use

Email Notifications

Support Email: Email address to send support requests submitted from the Customer Care Form. If blank, requests are sent to the default address configured for the platform.

On Call Email: Email address to send emergency support requests submitted from the Customer Care Form. If blank, requests are sent to the default address configured for the platform.

System Notification Email: Internal support email address to send system messages, such as heartbeat and Theme edit notifications.

Client Notification Email: Client email address to send system errors, such as campaign failures and Relational imports. This is used in addition to the Notification email for the campaign and the Admin Email set in the List properties.

Default Bounce Address: Email address to use when a List is deployed with no Bounce Address defined. If your Realm has a single Bounce Address, then it should be set here in the format: [email protected]. For more information about Bounce Address setup, see Bounce Address.

API

Customer is allowed to use the API: Select to allow use of all APIs

Customer can send to cc in one-off messages: Select to allow use of the CC in HTTP API send commands only

Customer is allowed to send attachments via API: Only available to very specific clients using Rest API. (new in 13.00.0)

Size limit (in Kilobytes): Limit the size of attached file.

Report External ID: Rest API stores a submitted External ID for some commands. Enable to allow reporting of the External ID in the Event Wizard reports. (new in 13.03)

Tracking

Base URLs: Define one or more BaseURLs for tracking. URLs must be prefixed with http:// or https://. The BaseURLs are available to select in the List Properties.

If removing base urls, also remove from lists (this time only): When deleting, select to remove BaseURL from existing lists

Children see these values in their dropdown list: Share to child realms.

Marketing Virtual MTA Tag: Define one or more VMTAs to use for publishing. The VMTAs are available to select in List Properties.

If removing VMTAs, also remove from lists (this time only): When deleting, select to remove VMTA from existing lists

Children see these values in their dropdown list unless otherwise defined: Share to child realms if child does not have VMTAs defined

Transactional Virtual MTA Tag: Define one or more VMTAs to use for transactional publishing via API commands. The VMTAs are NOT available to select in List Properties. (new in 14.13.00)

If removing VMTAs, also remove from lists (this time only): When deleting, select to remove VMTA from existing lists

Children see these values in their dropdown list unless otherwise defined: Share to child realms if child does not have VMTAs defined

Sync Enabled: Select to allow the use of Event Macros. The option to define Event Macros will appear in the List Properties.

Track sends: Select to create a tracking event for every piece of mail sent through the UI. This does affect publishing and database performance for very large campaigns. This is only available on Broadcasters.

Track browser stats: Select to track which browser an event was initiated from. This is only available on Broadcasters.

Retain Tracking Data: Select to determine how often tracking data will be archived. If none specified, tracking data will not be deleted at all. The data is retained 18 months by default.

Archive rolled-up data: Store a compressed version of the deleted data

Tracking Ignore IPs: When tracking events are found associated to a specific IP or IP Range, do not record the tracking event for reporting, but record that it was ignored. Used to block spam attacks.

Prevention

Import Prevention: Prevent Realm from adding new subscribers.

Extraction Prevention: Prevent Realm from exporting data or running reports

Deployment Prevention: Prevent Realm from deploying campaigns

Deployment

Priority Boost: Select to put campaigns sent from this realm at the head of the publishing queue. This is useful for Realms that send time sensitive campaigns, such as Breaking News releases. This cannot be set if Throttling is enabled.

Campaign Throttling: Select to allow throttling published messages on a per campaign basis. This allows you to determine how many messages to send per hour from the system.

Realm Throttling: Select to allow throttling published messages for every campaign at a specific number of messages per hour.

Remarketing Limit:

Data Storage (Relational Data)

Use Relational Database: Select to allow creation of Relational Database tables and data storage. This option must be enabled in order to integrate with Rapleaf and Windsor Circle.

Max Table Depth: Maximum number of tables that can be nested, where the Subscribers table is always the first depth. Default is 2 tables deep.

Max Number of Columns: Maximum number of data columns allowed in each table. Default is 30 columns.

Foreign Key Required: Always set to True, no option to change this setting.

Integration

Analytics: Select to allow integration with Omniture or Google Analytics. A contract is required to use Omniture integration.

Google Analytics supports customization of five UTM tags. If set, every tracking URL in a message will use the tagsdefined in the Realm Settings by default, unless otherwise defined at the time of campaign deployment. DefaultGoogle Analytics attributes are added as follows (*New Google Analytics UTM Content and UTM Term tags added in v11.10.0 release.):

UTM Source: WhatCountsEmail

UTM Medium: List Name plus Segmentation Rule Name deployed

UTM Campaign: Template Name deployed

UTM Content: No default

UTM Term: No default

Conversion Tracking:

Video Integration: Select to allow publishing Video in messages, and set the Video Key.

Social Networking: Select to allow publishing tracked links to supported Social Networks. Enabled by default.

Store FTAF Recipient: Select to store email address of FTAF friends. This option should not be enabled in countries that prohibit storing this data.

Deliverability: Select to allow use of Deliverability Reporting and set default reporting options. A delivery services contract is required to run reports.Available to Private Label Admins.

Subscription Management

Double Opt in:When a new subscription request is made by the Subscriber, a confirmation email will be sent to the address, and the Subscriber must click a link to confirm the request.

Confirmation captcha: Select to require all Subscribe requests to be confirmed using a CAPTCHA generated code.Available to Private Label Admins.

Email Unsub: Select to make all Unsubscribe requests global rather than list level opt-outs.Available to Private Label Admins.

Soft Bounce Thresholds: Select to allow Soft Bounces to convert to Hard Bounce and remove subscription after defined number of bounces in time frame.Available to Private Label Admins.

Profile Updates: Select to skip the confirmation step when a subscriber changes their profile.Available to Private Label Admins.

Registration Profile: Select an LDAP or RADIUS Registration Profile. This is only available on Broadcasters.Available to Private Label Admins. Deprecated in 11.0, but not yet removed.

New Custom Fields:Custom Fields will be stored in a new table for the Realm to improve reporting and segmentation. All realms created as of 8/8/2019 will use the new custom fields methods. (new in 14.14.00)