Follow

Send One-Off Message

The Send One-Off Message command allows you to send a single transactional style message to a 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 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=reply@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 subscriber.  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 Subscriber 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 Subscriber 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 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, the message will be sent.  A Subscriber 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 Subscriber'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 Subscriber initiated events. 

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

Yes

Identifier of the list properties to use. Required for List unsubscribe to function.

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 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, 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. 

The Campaign Name can be no longer than 100 characters.

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

 

 

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

Comments

Powered by Zendesk