Follow

Subscribe and Send One-Off Message

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&to=jane@domain.com&data=email^jane@domain.com

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 'jane@domain.com' 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&to=jane@domain.com&vmta=myvmta&from=%22Decorative%22%20%3Cfrom@domain.com%3E&reply_to_address=reply@domain.com%3E&data=email,first,custom_age^jane@domain.com,Jane,32

If it doesn't already exist, a new subscription will be created for ‘jane@domain.com’ 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 HTML content from Template ‘42’ will be sent to ‘jane@domain.com’.  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&to=jane@domain.com&from="Decorative"%20<from@domain.com>&plain_text_body=This%20is%20plain%20text%20body&html_body=This%20is%20html%20body&charset=ISO-8859-1&subject=Body%20Subject&data=email,first^jane@domain.com,Jane

The results for either would appear as follows:

SUCCESS: mail will be sent to jane@domain.com

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&to=jane@domain.com&customer_key=11293&vmta=myvmta&from=%22Decorative%22%20%3Cfrom@domain.com%3E&reply_to_address=reply@domain.com%3E&data=customer_key,email,first,custom_age^11293,jane@domain.com,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" <mycustomemail@domain.com>

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 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 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]

CC To Address

 

Email address to send a copy of the message.

cc=[email address]

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 by using 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^myemail@mydomain.com

data=customer_key,email^123abc,myemail@mydomain.com

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^myemail@mydomain.com,Jane,f

data=[fields]

d=[fields]

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 or the List must be set to use Sticky Campaigns to convert the URLs to tracked URLs.

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]

 

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

Comments

Powered by Zendesk