Follow

Send One-Off Message

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, List, Template, Format, and Data.

cmd=send&list_id=5&template_id=42&format=1&data=email^jane@domain.com

The command is ‘send’, 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 'jane@domain.com'.

The Send command expects at least one field in the Data argument.  The email address of the subscriber is always required to send a message.  If the subscriber does not exist, or is not subscribed to the list, a Subscription and Subscriber record will be created.

Example

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

cmd=send&realm=myrealm&list_id=5&template_id=42&campaign_name=my+campaign&subject=New%20Subject&format=2&data=email,first,custom_age^jane@domain.com,Jane,32

A new Subscriber record will be created for the email address ‘jane@domain.com’ in the realm ‘myrealm’, a child of the Realm defined in the header.  The Subscriber record will contain the First Name, Last Name, and Age of the subscriber.  Once created, a subscription will also be created for List ‘5’.  A message will then be sent to the subscriber using the List Properties from List ‘5’ and the HTML content in Template ‘42’.

If Sticky Campaigns is enabled for the list, and 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.

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 data argument along with email.  For example:

cmd=send&realm=myrealm&list_id=5&template_id=42&campaign_name=my+campaign&subject=New%20Subject&format=2&data=customer_key,email,first,custom_age^11293,jane@domain.com,Jane,32

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

Additional Considerations

The Send command supports several special arguments.

Subscription vs. No Subscription

The 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.  If the subscriber does not exist, or is not subscribed to the list, a Subscription and Subscriber record will be created.

Tracking as Campaigns

 

By default the 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 to LISTS > 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 data file.  Define the Campaign Name in the header to associate all Send commands in the Data file to the same campaign.  Define the Campaign Name in the specific Send command to override the header definition.  

When you submit the Data File for processing, it will check to see if a campaign already exists with the list_id and campaign_name.  If so, tracking for this one-off message will be associated to that campaign.  If not, a new campaign will be created and tracked. 

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 command will fail if an Optout record exists for the specified email address.  It will also fail if an invalid list or template is specified, or if no content is defined for the specified email format.  The failure will be reported in the FTP API confirmation email.

Arguments

The command supports the following arguments:

Name

Req?

Description

Argument

Command

Yes

Defines the command to use.

cmd=send

Realm

 

Name of the realm to run the command.  This is optional and only necessary when submitting files to a parent realm in order to manipulate a child realm.

realm=[realm_name]

List

Yes

Identifier of the list properties to use. If you are using one file to perform the same command for several lists, group the command lines in your file by Command and List.  This will improve processing efficiency. 

Alternately, define the list in the header instead of per command.  This must refer to a valid list with From and Reply-to.

list_id=[list_id]

Template

Yes

Identifier of the template content to send.  In the template, both Plain Text and HTML 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]

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 by using the Sticky Campaigns option in the Advanced List Properties.

See Track as Campaigns above for more information.

campaign_name=[campaign_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] 

Data

 

The Email data field is always required.  Additional fields are optional.

data=[fields]

 

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

Powered by Zendesk