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, Realm, Password, List, Template or Body, Format, and To.
api_web?r=myrealm&p=mypass&c=send&list_id=5&template_id=42&format=1&to=jane@domain.com
The command is ‘send’, 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', and the message will be sent to the email address 'jane@domain.com'.
Example
Using many commands and arguments (please note the command is wrapped for display purposes only):
api_web?r=myrealm&p=mypass&c=send&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=%3Creply@domain.com%3E&data=email,first,custom_age ^jane@domain.com,Jane,32
A message from List ‘5’ with plain text content from Template ‘42’ will be sent to ‘jane@domain.com’. If the Template contains tags for email, first, and the custom field age, then each will be filled with the data defined in the call, instead of data defined in the database. 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
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 can also include it in the data argument along with email. For example:
api_web?r=myrealm&p=mypass&c=send&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.
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 override these fields use the "data" argument. Like other commands that support the data argument, you can pass general Contact Data and Custom Data, however it will not 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, the message will be sent. A Contact Record will be created in the database with no Subscription. If the template requires custom data, you can send it through the command using the "data" argument. Custom data passed through the "send" command will only be used to populate the email and not saved to the Contact's record. If you require this data to be saved, use the Sub and Send command.
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 Send command outputs either a SUCCESS or FAILURE message.
SUCCESS
The 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 Send command will fail for several reasons. The result format is:
FAILURE: [Reason]
Arguments
The Send command support the following arguments:
|
Name |
Req? |
Description |
Argument |
|
Command |
Yes |
Defines the command to use. |
cmd=send c=send |
|
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 |
Yes |
Identifier of the list properties to use. Required for List unsubscribe to function. * List Name added in v13.0.0, coming soon |
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] |
|
CC To Address |
Email address to send a copy of the message. |
cc=[email address] |
|
|
Template |
* |
Identifier of the template content to send. If no template defined in the call, the default template defined in the List properties will be used. If no template is defined in list, the body must be manually defined. In the template, both Plain Text and HTML must be defined in order to send MIME. * Template Name added in v13.0.0, coming soon |
template_id=[template_id] template_name=[template%20name] |
|
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 passed. |
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 campaign_name must be passed. |
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. 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 optouts 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 |
Data fields are optional to pass data into %%$[field]%% tags in the template, such as ‘email’ or custom fields, if not already stored in the database. |
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 Realm 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 Realm, 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] |