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 contact. These messages are individually created and sent, but can be tracked together 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 contact.
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 contact already exists, the data will be updated in the contact record.
Once the subscription and contact 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:
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 contact. 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
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:
api_web?r=myrealm&p=mypass&c=subandsend&list_id=5&format=99&force_sub=1&data=email,first,last,custom_gender,publishing_flight_id^jane@domain.com,Jane,Doe,female,25
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 Contact 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 Contact 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 contact 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 Contact'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 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, 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 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 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 |
* |
Contact 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 a campaign_name must be sent. |
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 a campaign_name must be sent. |
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 |
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] |
|
|
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 contacts exist with the same email address and different first name, you must indicate which contact should receive the message using first name and duplicate setting. |
first_name=[first_name] &dup=[0,1] DEFAULT==0 |
|
|
Ignore Optout |
If a contact 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 Contact 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 contact 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] |
|
Email Snapshot |
|
Email Snapshot will create and store the HTML and image screenshot of each message sent, including contact-specific personalization, if the message is tracked as a Campaign (see Campaign Name above). If your Realm is enabled for Email Snapshot, to store a copy of each message, set the 'snapshot' argument to 1 and include a Campaign Name. 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_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 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] |
*Publishing Flight added in v16.16