WS_MailUpSend.SendNewsletter

Used to send a bulk email campaign. It supports scheduling of the campaign (if a schedule is not specified, the message is queued up immediately).


 

Method parameters

  • string SendNewsletter(string accessKey, int listID, int newsletterID, Option[] options)
    • accessKey: access key obtained using the LoginFromId method
    • newsletterID: Id of the message returned by the WS_MailUpSend.CreateNewsletter
    • options: an array of key/value pairs for options setting
      • from_email: a string containing the sender email address. If not specified, the default value for the list will be used
      • from_name: a string containing the sender name. If not specified, the default value for the list will be used
      • clear_stats: a boolean value to enable/disable the deletion of statistics referred to previous mailings of the same message
      • send_to: a mandatory string indicating to whom the message will be sent. If send_to=ALL the message is sent to all subscribers, if send_to=RECIPIENTS the message is sent to specific email addresses, if send_to=GROUPS the message is sent to subscribers to specific groups
      • recipients: a string indicating the recipients of the message. Its content depends on the value assumed by "send_to". If send_to = ALL, "recipients" parameter is ignored and the message is sent to all the recipients in the list; if send_to=RECIPIENTS, "recipients" parameter contains a list of email addresses separated by the ";" character; if send_to=GROUPS, the "recipients" parameter contains the IDs of the recipient groups, separated by the ";" character 
      • exclude: a string containing the IDs of the groups to be excluded from the sending, separated by the ";" character
      • filters: a string containing the IDs of the filters separated by the ";" character, to be used to retrieve the recipients of the message
      • filters_as: a string indicating how to apply the filters: if filters_as=AND, all the conditions in the filters have to be met; if filters_as=OR, at least one of them
      • deliverydt: a string containing date and time of scheduled delivery, in the format yyyyMMddHHmmss. If not specified, the sending starts immediately, and in case another sending is in progress the message is queued
      • timezone: an integer indicating the time zone
      • campo1… campo<nn> = in case the "recipients" parameter contains a list of email addresses, you can indicate one or more personal data fields to be updated. Each option "campo<nn>" is a string containing the values for the personal data field <nn> referred to the email addresses indicated in the "recipients" parameter. Values must be separated by the ";" character

If error code=0, the message will contain the ID of the sending

SOAP Examples

Sample requests

SOAP request (RECIPIENTS, immediate)
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:ws="http://services.mailupnet.it/WS">
	<soap:Header/>
	<soap:Body>
		<ws:SendNewsletter>         
			<ws:accessKey>HzAgwRRJaAKBtkgNWpkAuURfV4SxMm6T3HJegRuSkUivKJElNNcmSQe8nqGyoM9</ws:accessKey>
			<ws:listID>2</ws:listID>
			<ws:newsletterID>84</ws:newsletterID>
			<ws:options>
				<ws:Option> <ws:Key>send_to</ws:Key> <ws:Value>RECIPIENTS</ws:Value> </ws:Option>
				<ws:Option> <ws:Key>from_name</ws:Key> <ws:Value>Your favorite dealer</ws:Value> </ws:Option>
				<ws:Option> <ws:Key>recipients</ws:Key> <ws:Value>mike@example.com</ws:Value> </ws:Option>
			</ws:options>
		</ws:SendNewsletter>
	</soap:Body>
</soap:Envelope>
SOAP request (ALL, immediate)
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:ws="http://services.mailupnet.it/WS">
   <soap:Header/>
   <soap:Body>
      <ws:SendNewsletter>         
	<ws:accessKey>HzAgwRRJaAKBtkgNWpkAuURfV4SxMm6T3HJegRuSkUivKJElNNcmSQe8nqGyoM9</ws:accessKey>
	<ws:listID>2</ws:listID>
	<ws:newsletterID>84</ws:newsletterID>
	<ws:options>
		<ws:Option> <ws:Key>send_to</ws:Key> <ws:Value>ALL</ws:Value> </ws:Option>
		<ws:Option> <ws:Key>from_name</ws:Key> <ws:Value>Your favorite dealer</ws:Value> </ws:Option>
        </ws:options>
      </ws:SendNewsletter>
   </soap:Body>
</soap:Envelope>
SOAP request (RECIPIENTS, scheduled)
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:ws="http://services.mailupnet.it/WS">
<soap:Header/>
<soap:Body>
	<ws:SendNewsletter>
	<ws:accessKey>HzAgwRRJaAKBtkgNWpkAuURfV4SxMm6T3HJegRuSkUivKJElNNcmSQe8nqGyoM9</ws:accessKey>
	<ws:listID>2</ws:listID>
	<ws:newsletterID>84</ws:newsletterID>
	<ws:options>
		<ws:Option> <ws:Key>send_to</ws:Key> <ws:Value>RECIPIENTS</ws:Value> </ws:Option>
		<ws:Option> <ws:Key>from_name</ws:Key> <ws:Value>Your favorite dealer</ws:Value> </ws:Option>
		<ws:Option> <ws:Key>from_email</ws:Key> <ws:Value>test@nweb.it</ws:Value> </ws:Option>
		<ws:Option> <ws:Key>recipients</ws:Key> <ws:Value>mike@example.com</ws:Value> </ws:Option>
	    
		<!-- Use the options below to schedule delivery at 04/09/2012 14:30:00  GMT +1 -->
		<ws:Option> <ws:Key>deliverydt</ws:Key> <ws:Value>20120904143000</ws:Value> </ws:Option>
		<ws:Option> <ws:Key>timezone</ws:Key> <ws:Value>0</ws:Value> </ws:Option>
	</ws:options>
	</ws:SendNewsletter>
</soap:Body>
</soap:Envelope>

Sample responses

SOAP response (immediate)
<SendNewsletterResult>
	<errorCode>0</errorCode>
	<errorDescription></errorDescription>
	<listID>2</listID>
	<newsletterID>84</newsletterID>
	<deliveryID>179</deliveryID>
	<deliveryStatus>Sending in progress</deliveryStatus>
</SendNewsletterResult>
SOAP response (scheduled)
<SendNewsletterResult>
	<errorCode>0</errorCode>
	<errorDescription></errorDescription>
	<listID>2</listID>
	<newsletterID>84</newsletterID>
	<deliveryID>190</deliveryID>
	<deliveryStatus>Delivery scheduled at 04/09/2012 14:30:00  GMT 1</deliveryStatus>
</SendNewsletterResult>

Recipient fields (merge tags)

You can pass to the system values that will be saved in the recipient database as Recipient fields, and can be used in the message as merge tags (dynamic fields).

The number of elements indicated for each "campo<nn>" parameter must match the number of addresses in the "recipients" parameter.

For example, let's say the message is sent to three recipients. The recipients parameter will look as follows:

recipients=johnsmith@example.com;pauljohnson@example.com;anntaylor@example.com

 

Now let's assume that you want to pass to the system the recipients' first and last name as part of the API call. Let's also assume that those fields are saved in the first two Recipient fields (campo1 and campo2). The API call will have to include 3 items for each semi-colon separated array of values:

campo1=John;Paul;Ann
campo2=Smith;Johnson;Taylor


In case of empty personal data fields, the number of elements must always be the same. In the example below, empty values are passed for the second recipient:

campo1=John;;Ann
campo2=Smith;;Taylor

Code samples

Ruby
# Refer to https://mailup.atlassian.net/wiki/display/mailupapi/MailUp+RubyGem for gem information.
require 'mailup'
m = MailUp::Send.new('username', 'password')
m.send_newsletter(:newsletterID => 3, "Options" => {:from_email => '..."})
# => <SendNewsletterResult><errorCode>0</errorCode><errorDescription></errorDescription>...</SendNewsletterResult>"
PHP
<?php
$WsSend = new MailUpWsSend(); //MailUpWsSend class handles endpoints and access key
$WsSend->loginFromId();
//...
// Prepare sending of message 294 to recipients of group 481 (that belong to list 66)
$sendNewsletterData = array("listID" => "66",
						   "newsletterID" => "294",
						   "options" => array(						   
										array("Key" =>"from_email", "Value" => "sender@example.com"),
										array("Key" =>"from_name", "Value" => "Your Dealer"),
										array("Key" =>"send_to", "Value" => "GROUPS"),
										array("Key" =>"recipients", "Value" => "481"))
					);
					
$WsSend->sendNewsletter($sendNewsletterData);
$WsSend->logout();
?>