BulkJobSubmit v3.1

BulkJobSubmit is used to send a email message to a list of one or more recipients.  There is no hard limit on the size of the list and millions of emails can be sent from a single invocation of this API.  To use this API, you must create an XML file that contains a list of all the recipients and place it on an HTTP server where it can be retrieved by the MessageGears system.  Then you make an API call and supply the URL where the recipient file is located along with the HTML and text template data as described below.  MessageGears will then retrieve the recipient file and perform a “mail merge” with the supplied content to generate the individual email messages.

Prior Versions

Required Parameters

Parameter Personalizable Description
Action BulkJobSubmit
AccountId The MessageGears account id to which this item belongs.
ApiKey A secret key only known by you. Keep this key confidential.
FromAddress
Yes
The "from email address" value. This field can be personalized using one of the supported template languages.
SubjectLine
Yes
The value used as the subject line. You can personalize this field using one of the supported template languages.
RecipientListXmlUrl A URL pointing to a file that contains a list of recipient data. The file may be compressed using the "ZIP" or "GZIP" algorithms. Supported protocols are http, https, and Amazon S3 . The referenced file must have a ".xml" extension if uncompressed, ".zip" if compressed using ZIP, and ".gz" if compressed using Gzip.

Click here for more information.
HtmlTemplate
Yes
The HTML template used for the HTML part of the email messages. At least one template must be provided (Text or HTML). If both are provided then a “multipart” message is sent and each email recipient’s email reader determines which content type to display.
TextTemplate
Yes
The text template used for the text part of the email message.

Optional Parameters

Parameter Personalizable Description
FromName
Yes
The "from name" value. This header is supported by most email clients and displays in place of (or sometime along with) the “from email address” in the recipients email reader.
OnBehalfOfName
Yes
Sets the "On Behalf Of" name part of the "Sender" header.

Click here for more information regarding the use of OnBehalfOf.
OnBehalfOfAddress
Yes
Sets the "On Behalf Of" email address part of the "Sender" header.
ReplyToAddress
Yes
This email address is used when the client selects "reply to" in their email reader. If not specified, the from address is used.
TemplateLanguage Valid values are: FREEMARKER or VELOCITY. If no value is specified, FREEMARKER is used by default.

Click here for more information regarding dynamic email content.
NotificationEmailAddress If this value is specified, any errors that are encountered in processing the job are emailed to this address. This can be very helpful for initial development and testing.
AttachmentUrl.n The URL where the attachment file is located. As many as 5 attachments can be supplied. Each attachment must have the appropriate suffix (i.e. .1, .2, .3, .4, .5).

Click here for more information regarding attachments.
AttachmentContent.n The base64 encoded string containing the attachment content. As many as 5 attachments can be supplied. Each attachment must have the appropriate suffix (i.e. .1, .2, .3, .4, .5).

Click here for more information regarding attachments.
AttachmentName.n The name displayed in the email message for the attached file. This is an optional field and if not provided, the name of the file is used as the attachment name.
AttachmentContentType.n The content type associated with the attachment.
CharacterSet The character set in which the email message will be encoded. If this field is not set, the default value of UTF-8 is used.

Click here for a full list of available character sets.
AutoTrack If set to "true" (case insensitive) all links in the HTML content will be made trackable. Otherwise, they will not. If true, any link inside an anchor tag, or image map tag will be marked as trackable. If the tag specifies a "name" attribute, the name will be set as the link name in your activity data.

Click here for more information.
UrlAppend
Yes
Use this optional field to specify a string to be appended to each trackable link in your HTML content. This parameter will only be accepted if the AutoTrack option above is set to "true". It can be helpful when used in conjunction with a web analytics system such as Google Analytics to add your campaign Id and other data to each of your links.

Click here for more information.
CustomTrackingDomain This optional field is used to provide a custom domain name to be used for trackable links and the open tracking URL. You must set a CNAME in your DNS that points to www.messagegears.net. Please test this carefully before using. Example: http://www.mycompany.com (please include the protocol/prefix).

Click here for more information.
ContextDataXml This field is used to supply data to the template that is not directly related to the recipient. For example, this field could contain data about weekly airfare specials by city. The template could then select only the fares that originated from the same city as the recipients home. This helps make it easy to create templates with relevant data for each recipient.

Click here for more information.
HeaderName.n The name of a custom header to be included with the message. You may have up to 5 custom headers each with the appropriate suffix (i.e. .1, .2, .3, .4, .5).

Click here for more information regarding customer headers.
HeaderValue.n The value of the header.
CorrelationId This field allows you to supply your own job id. This Id will be returned with all reporting data (including the real-time data feed) and can make it much easier to match events coming out of MessageGears with the job they belong to in your own system.
UnsubscribeHeader If set to "true" (case insensitive) a header named "List-Unsubscribe" will be added to your message. Otherwise, it will not. This header is used by several ISPs (most notably GMail) and allows users to click an unsubscribe button in their email reader. You will receive an "unsubscribe" event in your activity data for each click of the unsubscribe button. This is the same event that would result from an unsubscribe link included in your HTML template using the ${Gears.unsubscribe()} Freemarker command.

Click here for more information.

Programming Examples

Request

https://api.messagegears.net/3.1/WebService
?Action=BulkJobSubmit
&AccountId=123456789
&ApiKey=8bb6118f8fd6935ad0876a3be34a717d32708ffd
&FromName=Customer Support
&FromAddress=customer.support@mycompany.com
&SubjectLine=Welcome!
&HtmlTemplate=<html>Thank you for enrolling in our support forum.</html>
&TextTemplate=Thank you for enrolling in our support forum.
&RecipientListXmlUrl=http://www.mycompany.com/file/WelcomeRecipients.xml
&TemplateLanguage=FREEMARKER

Response

<BulkJobSubmitResponse>
    <RequestId>b23510-82279647-13fa-4930-8338-ec85988b6bed</RequestId>
    <Result>REQUEST_SUCCESSFUL</Result>
</BulkJobSubmitResponse>

Click here to see more details about using the MessageGears Java SDK
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
package com.messagegears.sdk.examples;
 
import java.io.File;
import java.io.FileInputStream;
import java.io.IOException;
import java.io.UnsupportedEncodingException;
 
import org.apache.commons.io.FileUtils;
 
import com.messagegears.sdk.MessageGearsClient;
import com.messagegears.sdk.MessageGearsProperties;
import com.messagegears.sdk.aws.MessageGearsAwsClient;
import com.messagegears.sdk.aws.MessageGearsAwsProperties;
import com.messagegears.sdk.exception.MessageGearsClientException;
import com.messagegears.sdk.model.request.BulkJobSubmitRequest;
import com.messagegears.sdk.output.ScreenWriter;
import com.messagegears.sdk.v3_1.BulkJobSubmitResponse;
 
public class BulkJobExample {
 
    public static final String MY_EMAIL_ADDRESS = "place your email address here";
    public static final String S3_BUCKET = "place your S3 bucket name here";
    public static final String XML_FILE_NAME = "recipients.xml";
    public static final String MY_MESSAGEGEARS_ACCOUNT_ID = "place your MessageGears account id here";
    public static final String MY_MESSAGEGEARS_API_KEY = "place your MessageGears api key here";
    public static final String MY_AWS_ACCOUNT_ID = "place your AWS account id here";
    public static final String MY_AWS_SECRET_KEY = "place your AWS secret key here";
 
    public static void main(String[] args) {
        // Create the properties object containing the necessary properties
        MessageGearsProperties props = new MessageGearsProperties();
        props.setMyMessageGearsAccountId(MY_MESSAGEGEARS_ACCOUNT_ID);
        props.setMyMessageGearsApiKey(MY_MESSAGEGEARS_API_KEY);
 
        // Create the MessageGears client object
        MessageGearsClient client = new MessageGearsClient(props);
 
        // Create a bulk job request
        BulkJobSubmitRequest request = new BulkJobSubmitRequest();
 
        // Create a String containing the recipient XML for 2 emails
        // You would probably construct this list by querying your database and streaming the XML data to a file.
        String recipientListXml =
            "<RecipientList>" +
                "<Recipient><EmailAddress>" + MY_EMAIL_ADDRESS + "</EmailAddress><FirstName>Recipient 1</FirstName></Recipient>" +
                "<Recipient><EmailAddress>" + MY_EMAIL_ADDRESS + "</EmailAddress><FirstName>Recipient 2</FirstName></Recipient>" +
            "</RecipientList>";
 
        // Copy the XML to Amazon S3 where it can be retrieved by MessageGears
        String recipientFileName = pushRecipientXmlFile(recipientListXml);
 
        // Set the message content
        request.setFromName("MessageGears");
        request.setFromAddress("no-reply@messagegears.com");
        request.setSubjectLine("MessageGears - Reliable Message Delivery");
        request.setRecipientListXmlUrl("s3://" + S3_BUCKET + "/" + recipientFileName);
        request.setHtmlTemplate("Hello, ${Recipient.FirstName}!");
 
        // Execute the request
        BulkJobSubmitResponse response = client.bulkJobSubmit(request);
 
        // Print the result (success or failure)
        ScreenWriter.printResponse(response);
    }
 
    private static String pushRecipientXmlFile(String recipientListXml) {
        // Create the AWS properties object
        MessageGearsAwsProperties awsProps = new MessageGearsAwsProperties();
        awsProps.setMyAwsAccountKey(MY_AWS_ACCOUNT_ID);
        awsProps.setMyAwsSecretKey(MY_AWS_SECRET_KEY);
 
        // Create the AWS client object
        MessageGearsAwsClient awsClient = new MessageGearsAwsClient(awsProps);
 
        try {
            // write local temp file
            File tempFile = new File(XML_FILE_NAME);
            FileUtils.writeStringToFile(tempFile, recipientListXml);
 
            // compress temp file
            File compressedFile = awsClient.compressFile(tempFile);
 
            // delete the file from s3 since it might already exist
            awsClient.deleteS3File(S3_BUCKET, compressedFile.getName());
 
            // upload the compressed xml file to S3
            awsClient.putS3File(new FileInputStream(compressedFile), S3_BUCKET, compressedFile.getName());
 
            // cleanup temp file and local compressed file
            compressedFile.delete();
            tempFile.delete();
 
            return compressedFile.getName();
        } catch (UnsupportedEncodingException usee) {
            throw new MessageGearsClientException("Unsupported encoding type.");
        } catch (IOException e) {
            throw new MessageGearsClientException("IOException - Failed to upload recipient list.");
        }
    }
}
package com.messagegears.sdk.examples;

import java.io.File;
import java.io.FileInputStream;
import java.io.IOException;
import java.io.UnsupportedEncodingException;

import org.apache.commons.io.FileUtils;

import com.messagegears.sdk.MessageGearsClient;
import com.messagegears.sdk.MessageGearsProperties;
import com.messagegears.sdk.aws.MessageGearsAwsClient;
import com.messagegears.sdk.aws.MessageGearsAwsProperties;
import com.messagegears.sdk.exception.MessageGearsClientException;
import com.messagegears.sdk.model.request.BulkJobSubmitRequest;
import com.messagegears.sdk.output.ScreenWriter;
import com.messagegears.sdk.v3_1.BulkJobSubmitResponse;

public class BulkJobExample {

    public static final String MY_EMAIL_ADDRESS = "place your email address here";
    public static final String S3_BUCKET = "place your S3 bucket name here";
    public static final String XML_FILE_NAME = "recipients.xml";
    public static final String MY_MESSAGEGEARS_ACCOUNT_ID = "place your MessageGears account id here";
    public static final String MY_MESSAGEGEARS_API_KEY = "place your MessageGears api key here";
    public static final String MY_AWS_ACCOUNT_ID = "place your AWS account id here";
    public static final String MY_AWS_SECRET_KEY = "place your AWS secret key here";

    public static void main(String[] args) {
        // Create the properties object containing the necessary properties
        MessageGearsProperties props = new MessageGearsProperties();
        props.setMyMessageGearsAccountId(MY_MESSAGEGEARS_ACCOUNT_ID);
        props.setMyMessageGearsApiKey(MY_MESSAGEGEARS_API_KEY);

        // Create the MessageGears client object
        MessageGearsClient client = new MessageGearsClient(props);

        // Create a bulk job request
        BulkJobSubmitRequest request = new BulkJobSubmitRequest();

        // Create a String containing the recipient XML for 2 emails
        // You would probably construct this list by querying your database and streaming the XML data to a file.
        String recipientListXml =
            "<RecipientList>" +
                "<Recipient><EmailAddress>" + MY_EMAIL_ADDRESS + "</EmailAddress><FirstName>Recipient 1</FirstName></Recipient>" +
                "<Recipient><EmailAddress>" + MY_EMAIL_ADDRESS + "</EmailAddress><FirstName>Recipient 2</FirstName></Recipient>" +
            "</RecipientList>";

        // Copy the XML to Amazon S3 where it can be retrieved by MessageGears
        String recipientFileName = pushRecipientXmlFile(recipientListXml);

        // Set the message content
        request.setFromName("MessageGears");
        request.setFromAddress("no-reply@messagegears.com");
        request.setSubjectLine("MessageGears - Reliable Message Delivery");
        request.setRecipientListXmlUrl("s3://" + S3_BUCKET + "/" + recipientFileName);
        request.setHtmlTemplate("Hello, ${Recipient.FirstName}!");

        // Execute the request
        BulkJobSubmitResponse response = client.bulkJobSubmit(request);

        // Print the result (success or failure)
        ScreenWriter.printResponse(response);
    }

    private static String pushRecipientXmlFile(String recipientListXml) {
        // Create the AWS properties object
        MessageGearsAwsProperties awsProps = new MessageGearsAwsProperties();
        awsProps.setMyAwsAccountKey(MY_AWS_ACCOUNT_ID);
        awsProps.setMyAwsSecretKey(MY_AWS_SECRET_KEY);

        // Create the AWS client object
        MessageGearsAwsClient awsClient = new MessageGearsAwsClient(awsProps);

        try {
            // write local temp file
            File tempFile = new File(XML_FILE_NAME);
            FileUtils.writeStringToFile(tempFile, recipientListXml);

            // compress temp file
            File compressedFile = awsClient.compressFile(tempFile);

            // delete the file from s3 since it might already exist
            awsClient.deleteS3File(S3_BUCKET, compressedFile.getName());

            // upload the compressed xml file to S3
            awsClient.putS3File(new FileInputStream(compressedFile), S3_BUCKET, compressedFile.getName());

            // cleanup temp file and local compressed file
            compressedFile.delete();
            tempFile.delete();

            return compressedFile.getName();
        } catch (UnsupportedEncodingException usee) {
            throw new MessageGearsClientException("Unsupported encoding type.");
        } catch (IOException e) {
            throw new MessageGearsClientException("IOException - Failed to upload recipient list.");
        }
    }
}

Click here to see more details about using the MessageGears .Net SDK
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
using System;
using System.IO;
using MessageGears;
using MessageGears.Model;
using MessageGears.Model.Generated;
using MessageGearsAws;
 
namespace MessageGears.Examples
{
    public class BulkSample
    {
        public const String MY_EMAIL_ADDRESS = "place your email address here";
        public const String S3_BUCKET = "place your S3 bucket name here";
        public const String XML_FILE_NAME = "recipients.xml";
        public const String MY_MESSAGEGEARS_ACCOUNT_ID = "place your MessageGears account id here";
        public const String MY_MESSAGEGEARS_API_KEY = "place your MessageGears api key here";
        public const String MY_AWS_ACCOUNT_ID = "place your AWS account id here";
        public const String MY_AWS_SECRET_KEY = "place your AWS secret key here";
 
        public static void Main ()
        {
            // Create the properties object containing the necessary properties
            MessageGearsProperties props = new MessageGearsProperties();
            props.MyMessageGearsAccountId = MY_MESSAGEGEARS_ACCOUNT_ID;
            props.MyMessageGearsApiKey = MY_MESSAGEGEARS_API_KEY;
 
            // Create the MessageGears client object
            MessageGearsClient client = new MessageGearsClient(props);
 
            // Create a bulk job request
            BulkJobSubmitRequest request = new BulkJobSubmitRequest();
 
            // Create a String containing the recipient XML for 2 emails
            // You would probably construct this list by querying your database and streaming XML data to a file.
            String recipientListXml =
                "<RecipientList>" +
                    "<Recipient><EmailAddress>" + MY_EMAIL_ADDRESS +
                                        "</EmailAddress><FirstName>Recipient 1</FirstName></Recipient>" +
                    "<Recipient><EmailAddress>" + MY_EMAIL_ADDRESS +
                                        "</EmailAddress><FirstName>Recipient 2</FirstName></Recipient>" +
                "</RecipientList>";
 
            // Copy the XML to Amazon S3 where it can be retrieved by MessageGears
            string recipentFile = pushRecipientXmlFile(recipientListXml);
 
            // Set the message content
            request.FromName = "MessageGears";
            request.FromAddress = "deliverability@messagegears.com";
            request.SubjectLine = "MessageGears - Reliable Message Delivery";
            request.RecipientListXmlUrl = "s3://" + S3_BUCKET + "/" + recipentFile;
            request.HtmlTemplate = "Hello ${Recipient.FirstName}!";
 
            // Execute the request
            BulkJobSubmitResponse response = client.BulkJobSubmit(request);
 
            // Print the result (success or failure)
            client.PrintResponse(response);
        }
 
        private static string pushRecipientXmlFile(String recipientListXml)
        {
            // Create the AWS properties object
            MessageGearsAwsProperties awsProps = new MessageGearsAwsProperties();
            awsProps.MyAWSAccountKey = MY_AWS_ACCOUNT_ID;
            awsProps.MyAWSSecretKey = MY_AWS_SECRET_KEY;
 
            // Create the AWS client object
            MessageGearsAwsClient awsClient = new MessageGearsAwsClient(awsProps);
 
            // write local temp file
            File.WriteAllText(XML_FILE_NAME, recipientListXml);
 
            // compress temp file
            string compressedFileName = awsClient.CompressFile(XML_FILE_NAME); 
 
            // delete the file from s3 since it might already exist
            awsClient.DeleteS3File(S3_BUCKET, compressedFileName);
 
            // upload the compressed xml file to S3
            awsClient.PutS3File(compressedFileName, S3_BUCKET, compressedFileName);
 
            // cleanup temp file and local compressed file
            File.Delete(XML_FILE_NAME);
            File.Delete(compressedFileName);
 
            // return the name of the compressed xml recipient file so it can be referenced later
            return compressedFileName;
                }
    }
}
using System;
using System.IO;
using MessageGears;
using MessageGears.Model;
using MessageGears.Model.Generated;
using MessageGearsAws;

namespace MessageGears.Examples
{
	public class BulkSample
	{
		public const String MY_EMAIL_ADDRESS = "place your email address here";
		public const String S3_BUCKET = "place your S3 bucket name here";
		public const String XML_FILE_NAME = "recipients.xml";
		public const String MY_MESSAGEGEARS_ACCOUNT_ID = "place your MessageGears account id here";
		public const String MY_MESSAGEGEARS_API_KEY = "place your MessageGears api key here";
		public const String MY_AWS_ACCOUNT_ID = "place your AWS account id here";
		public const String MY_AWS_SECRET_KEY = "place your AWS secret key here";

		public static void Main ()
		{
			// Create the properties object containing the necessary properties
			MessageGearsProperties props = new MessageGearsProperties();
			props.MyMessageGearsAccountId = MY_MESSAGEGEARS_ACCOUNT_ID;
			props.MyMessageGearsApiKey = MY_MESSAGEGEARS_API_KEY;

			// Create the MessageGears client object
			MessageGearsClient client = new MessageGearsClient(props);

			// Create a bulk job request
			BulkJobSubmitRequest request = new BulkJobSubmitRequest();

			// Create a String containing the recipient XML for 2 emails
			// You would probably construct this list by querying your database and streaming XML data to a file.
			String recipientListXml =
				"<RecipientList>" +
					"<Recipient><EmailAddress>" + MY_EMAIL_ADDRESS +
                                        "</EmailAddress><FirstName>Recipient 1</FirstName></Recipient>" +
					"<Recipient><EmailAddress>" + MY_EMAIL_ADDRESS +
                                        "</EmailAddress><FirstName>Recipient 2</FirstName></Recipient>" +
				"</RecipientList>";

			// Copy the XML to Amazon S3 where it can be retrieved by MessageGears
			string recipentFile = pushRecipientXmlFile(recipientListXml);

			// Set the message content
			request.FromName = "MessageGears";
			request.FromAddress = "deliverability@messagegears.com";
			request.SubjectLine = "MessageGears - Reliable Message Delivery";
			request.RecipientListXmlUrl = "s3://" + S3_BUCKET + "/" + recipentFile;
			request.HtmlTemplate = "Hello ${Recipient.FirstName}!";

			// Execute the request
 			BulkJobSubmitResponse response = client.BulkJobSubmit(request);

  			// Print the result (success or failure)
 			client.PrintResponse(response);
 		}

		private static string pushRecipientXmlFile(String recipientListXml)
		{
			// Create the AWS properties object
			MessageGearsAwsProperties awsProps = new MessageGearsAwsProperties();
			awsProps.MyAWSAccountKey = MY_AWS_ACCOUNT_ID;
			awsProps.MyAWSSecretKey = MY_AWS_SECRET_KEY;

			// Create the AWS client object
			MessageGearsAwsClient awsClient = new MessageGearsAwsClient(awsProps);

			// write local temp file
			File.WriteAllText(XML_FILE_NAME, recipientListXml);

			// compress temp file
			string compressedFileName = awsClient.CompressFile(XML_FILE_NAME); 

			// delete the file from s3 since it might already exist
			awsClient.DeleteS3File(S3_BUCKET, compressedFileName);

			// upload the compressed xml file to S3
			awsClient.PutS3File(compressedFileName, S3_BUCKET, compressedFileName);

			// cleanup temp file and local compressed file
			File.Delete(XML_FILE_NAME);
			File.Delete(compressedFileName);

			// return the name of the compressed xml recipient file so it can be referenced later
			return compressedFileName;
                }
 	}
}