Follow

Subscribe and Send One-Off Message

 
 

The Subscribe and Send One-Off Message command allows you to subscribe an email address 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.

Arguments

The Subscribe and Send command requires the following arguments: Command, List, Template, Format, and Data.

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

The command is ‘subandsend’, 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 and the message sent to the email address 'jane@domain.com'.

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

The Subscribe and Send command support the following arguments:

 

Name

Req?

Description

Argument

Command

Yes

Defines the command to use.

cmd=subandsend

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, the List properties must be set to Sticky Campaigns.  If you then define a campaign name, you can view the results as a single campaign.

A single list can have multiple campaigns by using a different Campaign Name. 

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]

 

 

Example

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

cmd=subandsend&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=subandsend&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.

Errors

A Subscribe and Send command will fail if an Opt out 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.

Additional Considerations

The Subscribe and 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 Subscribe and Send command sends a single message and does not track the resulting Subscriber initiated events.  To track one-off messages as a campaign, you must enable the Sticky Campaigns option in your List properties.  Do this through the web interface by logging in and then going 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.

Define the Campaign Name in the header to associate all Subscribe and Send commands in the Data file to the same campaign.  Define the Campaign Name in the specific Subscribe and 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.

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

Comments

Powered by Zendesk