The Send One-Off Message command allows you to send a single transactional style message to a contact. These messages are individually created and sent, but can be tracked together 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 contact is always required to send a message. If the contact does not exist, or is not subscribed to the list, a Subscription and Contact 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 Contact 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 Contact record will contain the First Name, Last Name, and Age of the contact. Once created, a subscription will also be created for List ‘5’. A message will then be sent to the contact using the List Properties from List ‘5’ and the HTML content in Template ‘42’.
If a campaign_name is included and the 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 contact. 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.
Publishing Flight Example
Some Realms have the ability to deploy campaigns to contacts in a specified order, called the Publishing Flight ID. If your realm has Publishing Flight enabled, then you can include the publishing_flight_id in the data argument along with email. For example:
cmd=sub&realm=myrealm&list_id=55&format=99&data=email,first,last,custom_gender,publishing_flight_id^jane@domain.com,Jane,Doe,female,25
Additional Considerations
The Send command supports several special arguments.
Subscription vs. No Subscription
The email address for the contact is always required, however the email address does not need to correspond to an existing contact. If an email address does not exist as a Contact or is not subscribed to the list, the message will be sent. If the contact does not exist, or is not subscribed to the list, a Subscription and Contact record will be created.
Tracking as Campaigns
By default the Send command sends a single message and does not track the resulting Contact 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.
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. 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 |
Yes |
The Email data field is always required. Additional fields are optional. |
data=[fields]
|
|
Email Snapshot |
Email Snapshot will create and store the HTML and image screenshot of each message sent, including contact-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. In addition, the &campaign_name must be included in the argument 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 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] |
*Publishing Flight added in v16.16