Batch Mail Service Guide

May 7, 2013

PUBLIC DISTRIBUTION

DST Systems, Inc
Electronic Solutions Division
333 W 11th St
Kansas City, MO 64105
www.dstsystems.com

ePriority Development
www.epriority.com


 ePriority Logo
© Copyright 2001-2015 DST Systems. All rights reserved. This file may not be copied in whole or in part in any medium without the express written consent of the owner.



Contents Up


Introduction Up

If you have not already done so, you should read the «ePriority Service Overview» before going further with this document as it will provide context for all ePriority features and functionality.

This document defines the ePriority Batch Email Service -- providing automated email generation and delivery. Batches sent to ePriority may be in any of the following formats:

  • ZIP archive file containing XML Instruction File and content files.
  • XML Instruction file containing inline content.

Instruction File formats and batch submission processes are defined in the following sections. The focus of this document is the Instruction File, which defines all content, recipients, and delivery information necessary to process the Batch.


XML Instruction File Up

XML Instruction Files should be named "epriority.xml". Below is a breakdown of the XML file itself with commentary.

You can view a complete XML schema at the following url: http://www.epriority.com/remote/batchservice.xsd.


Example Xml Instruction File Up

<?xml version="1.0" encoding="ISO-8859-1" ?>
<batch profile="default" xmlns:xsd="http://www.w3.org/2001/XMLSchema-instance" xsd:noNamespaceSchemaLocation="http://www.epriority.com/remote/batchservice.xsd">
A single root "batch" tag surrounds all other tags. Each batch points to the "default" ePriority Delivery Profile unless otherwise specified.


<template>
One or more <template> tags may be defined per batch. Each <template> describes a complete email including recipient list.


<content mfile="body.html" type="text/html" display="body" encoding="base64" charset="iso-8859-1">
PCFET0NUWVBFIEhUTUwgUFVCTElDICItLy9XM0MvL0RURCBIVE1MIDQuMCBUcmFuc2l0aW9uYWwv
L0VOIj4NCjwhLS0gc2F2ZWQgZnJvbSB1cmw9KDAwNDApaHR0cDovL2Vjb21tL3dpZXMvd2ViaW1w
PCFET0NUWVBFIEhUTUwgUFVCTElDICItLy9XM0MvL0RURCBIVE1MIDQuMCBUcmFuc2l0aW9uYWwv
L0VOIj4NCjwhLS0gc2F2ZWQgZnJvbSB1cmw9KDAwNDApaHR0cDovL2Vjb21tL3dpZXMvd2ViaW1w
PjwvQ0VOVEVSPjwvVEFCTEU+PC9CT0RZPjwvSFRNTD4NCg==
</content>
 Email content can be supplied inline within the XML file as shown above. Content supplied directly in the XML file must be encoded in base64 to protect the original format.

<content filename="body7345.txt" mfile="body.txt" display="body" type="text/plain" secure="n"/>
 In this example, the filename attribute is supplied - referencing another file within the Batch (TAR or ZIP).

<header>

<subject>This is a test subject</subject>
Subject of the email message.

<from address="from@dstoutput.com" name="George Smith"/>
Sender of this email message.

<reply address="reply@dstoutput.com" name="Customer Support"/>
Optional reply address.

</header>


<list>
<email id="3478 id2="66101 id3="GeorgeSmith">
Each email tag holds data unique to an email generated from this template. The "id" attribute is used for tracking purposes and is returned in tracking logs for client use.

<rcpt address="bgbenson@dstoutput.com" name="Ben Benson"/>
Defines the recipient address.

<cc address="ganonymous@dstoutput.com" name="Gayle Anonymous"/>
<cc address="banyone@dstoutput.com" name="Bob Anyone"/>
Optional CC recipients. Receive the same ePriority tracking and reporting capabilities as the target recipient (rcpt). The target recipient and CC recipients will have the same email id fields.

<bcc address="danonymous@dstoutput.com" name="Dan Anonymous"/>
<bcc address="eanyone@dstoutput.com" name="Earl Anyone"/>
Optional BCC recipients. Similar to CC, BCC receive the same ePriority tracking and reporting capabilities as the target recipient (rcpt). The target recipient and BCC recipients will have the same email id fields.

<pdata key="x" value="y"/>
<pdata key="x" value="y"/>
 <pdata> tags can optionally be used to define data for merging with email content.

<securekey>user password here</securekey>
If secure content is provided, each email will need a password defined to view encrypted content.

<content type="text/plain" mfile="NameOfAttachment.txt" display="attachment" encoding="base64">
RGVhciB7e2ZpcnN0TmFtZX19LApBIG5ldyBzdGF0ZW1lbnQgaXMgYXZhaWxhYmxl
IGZvciB5b3VyIGFjY291bnQ6IHt7YWNjb3VudE51bWJlcn19LiBZb3UgbWF5IGxv
Z2luIHRvIHZpZXcgeW91ciBzdGF0ZW1lbnQgYXQgaHR0cDovL3d3dy5kc3RzeXN0
ZW1zLmNvbS4KClNpbmNlcmVseSwKRFNUIE91dHB1dCBTdXBwb3J0Cg==
</content>
Attachments are optional. The securekey is not applicable to non-pdf attachments.

<content type="application/pdf" mfile="NameOfAttachment.pdf" display="attachment" encoding="base64">
RGVhciB7e2ZpcnN0TmFtZX19LApBIG5ldyBzdGF0ZW1lbnQgaXMgYXZhaWxhYmxl
IGZvciB5b3VyIGFjY291bnQ6IHt7YWNjb3VudE51bWJlcn19LiBZb3UgbWF5IGxv
Z2luIHRvIHZpZXcgeW91ciBzdGF0ZW1lbnQgYXQgaHR0cDovL3d3dy5kc3RzeXN0
ZW1zLmNvbS4KClNpbmNlcmVseSwKRFNUIE91dHB1dCBTdXBwb3J0Cg==
</content>
Attachments are optional. The securekey supplied with this email in this instruction file is required to view this secured pdf.
</email>

</list>

</template>
</batch>

XML Element Definitions Up

Element Attribute XML Type
batch profile NMTOKEN
content mfile CDATA
content filename CDATA
content type CDATA
content display fixed
content encoding fixed
content charset CDATA
content secure CDATA
subject n/a CDATA
from address CDATA
from name CDATA
reply address CDATA
reply name CDATA
email id NMTOKEN
rcpt address CDATA
rcpt name CDATA
cc address CDATA
cc name CDATA
bcc address CDATA
bcc name CDATA
pdata key CDATA
pdata value CDATA
securekey n/a CDATA

Batch File Up

Instruction Files may be submitted to ePriority as a standalone file if all content is provided inline (see use of the content "filename" attribute in the XML Instruction File section for details), otherwise the Instruction File and associated Content Files will need to be merged into a ZIP archive.

Batch File requirements are as follows:

  • File must be an Instruction File itself or contain an Instruction File.
  • Must not exceed 2 gigabytes in size. Ideally batches should be less than 500MB. Extremely large Batch Files are less efficient to process than small to medium batches. For example, if you have a 1.5 Gb batch it would be better to break it up into three batches of 500 Mb each.
  • Batch Filename Rules:
    • Ends with ".zip", or ".xml" to indicate the format
    • 1 to 35 characters in length - excluding file type extension(s)
    • Unique across all time
    • Composed of letters, digits, periods, underscores, and hyphens
    • Cannot begin with a period

The filename for a Batch File (excluding file type extensions) is also used as the Batch ID. This Batch ID is case sensitive. For example, a batch submitted under the name "prodRun10000-a.zip" will result in the ID "prodRun10000-a".


Batch Submission Up

Batch Files must be uploaded via FTP to ftp.epriority.com and placed in the "/batches" directory. Administrators of an ePriority account have access to view or change FTP credentials from the ePriority website. Please see your account administrator if you do not know the username or password for your ePriority FTP account.

After uploading the Batch File, a secondary Summary File must be uploaded to indicate the Batch File is ready for processing. The Summary File can be an empty file or a text file containing the byte count of the Batch File - in which case ePriority will check that the file upload was not interrupted.

Keep in mind that the Batch File should be uploaded as a binary file if it is of ZIP format.

Example FTP Session

$ ftp ftp.epriority.com
Connected to ftp.epriority.com.
220-
 ----------------------------------------------------------------------
 Welcome to ePriority's FTP Service

 This FTP service is logged and monitored at all times.  Use of this
 service and all computing resources of DST Systems implies knowledge
 and consent of DST Systems appropriate use policies.
 If you have an issue with this policy, please disconnect now and
 contact your DST Systems account representative.
 ----------------------------------------------------------------------

220 This is a private system - No anonymous login
Name (ftp.epriority.com:bob): bob
331 Password required for bob.
Password: #######
230 User bob logged in.
Remote system type is UNIX.
Using binary mode to transfer files.
ftp> cd batches
250 CWD command successful.
ftp> binary
200 Type set to I.
ftp> put 2002q1.zip
local: 2002q1.zip remote: 2002q1.zip
200 PORT command successful.
150 Binary data connection for 2002q1.zip (10.115.110.1,11717).
226 Transfer complete.
194560 bytes sent in 0.22932 secs (8.3e+02 Kbytes/sec)
ftp> put 2002q1.zip.sum
local: 2002q1.zip.sum remote: 2002q1.zip.sum
200 PORT command successful.
150 Binary data connection for 2002q1.zip.sum (10.115.110.1,11710).
226 Transfer complete.
18 bytes sent in 0.001125 secs (16 Kbytes/sec)
ftp> quit
221 Goodbye.

Batch Failure Conditions

If there are problems with an email, the email message will be rejected for delivery but remaining emails in the batch will be delivered. An entire batch will fail under the following conditions:

  • The Batch File or Instruction File structure is invalid
  • The Instruction File is missing
  • The target ePriority Delivery Profile does not exist
  • Content File(s) are missing
  • All emails in the batch failed to generate
  • An email in a secure batch contains more than one secure body
  • The ePriority Delivery Profile designates this batch as secure but no recipient secure key is provided.

Batch Resubmission

If a batch fails processing, it can be fixed and resubmitted under the same name/ID. In no other situation is a Batch ID reusable.


Instruction Value Types Up

Element Attribute Type Description
from address* ADDR Designates the return/sender email address.
from name CHAR Length: 1-64
 Name to display with the sender's address.
pdata key CHAR Allowed: a-z, A-Z, 0-9, period, hyphen, underscore
Length: 1-64
 Defines pdata key in the Instruction File within the email element. See «Pdata Tag (Message Personalization)» in the ePriority Overview Service Guide for more information about using this tag.
pdata value XML Length: 0-254
 Defines pdata value in the Instruction File within the email element.
batch profile N/A Identifies an established profile name. If undefined, the "default" profile will be used. (see «Delivery Profiles» in the ePriority Overview Service Guide.)
reply address ADDR Defines an alternative to the "From" address for reply mail. Not all mail clients or mail servers may use the two addresses in the same way. Additionally, there is no assurance that mail servers will not send bounced mail to the "reply" address instead of the "from" address.
reply name CHAR Length: 1-64
 Name to display with the reply address.
subject* n/a TEXT Restricted: tab, carriage return, newline
Length: 1-254
 This value used for the subject in the emails.
rcpt address* ADDR Defines the recipient email address.
rcpt name CHAR Length: 1-64
 Name to display with the recipient address.
cc address* ADDR Defines the cc email address.
cc name CHAR Length: 1-64
 Name to display with the cc address.
bcc address* ADDR Defines the bcc email address.
bcc name CHAR Length: 1-64
 Name to display with the bcc address.
email id* CHAR Allowed: a-z, A-Z, 0-9, period, hyphen, underscore
Length: 0-30
 Email identification. Should be unique for every email in the batch.
securekey n/a CHAR Restricted: single-quote, back-tick, space
Length: 7-20
 A password that the recipient of the secure message can use to decrypt the contents of the generated secure attachment. If the batch is considered secure and a securekey is not defined for every package, the batch will be failed.
content encoding N/A Values: "base64" only
 Identifies the MIME encoding scheme for the content part. (If content has already been encoded for email delivery).
content charset N/A Values: "US-ASCII", "ISO-8859-1", "UTF-8", "UTF-16BE", "UTF-16LE" or "UTF-16"
 Identifies the charcter set for the content part. ISO-8859-1 is assumed if this value is not set.
content filename* CHAR Restricted: single-quote, back-tick, space
Length: 1-100
 Filename or path of the content file within TAR Batch File. The filename must exactly match the filename or path used in building the TAR. This value must also be unique across the entire batch file as it is used to locate content parts during the package generation process.
content display* N/A Values: "body", "inline", or "attachment"
 Determines how the content is presented.
content mfile* CHAR Allowed: a-z, A-Z, 0-9, period, hyphen, underscore
Length: 1-32
 Assigns a filename for the email message. This is the name that will be used by the recipient's mail client when it saves an attachment. The "mfile" name only has to be unique within each message.
content secure BOOL Designates whether or not ePriority should treat this content as secure. (See Secure Content feature in the ePriority Overview Service Guide)
content type* CHAR Allowed: a-z, A-Z, 0-9, forward-slash
 MIME Content-Type of the file. The official list of MIME types registered with the IANA can be found «here». To name a file type that has not yet been officially sanctioned, see «RFC 1049». Some of the more commonly used file types in email are:

text/plain ASCII text
text/html HTML document
image/gif GIF image
image/jpeg JPEG image
application/pdf PDF document
application/msword Microsoft Word document


Data Types Up

CHAR Data Type

Any ASCII character in the hexadecimal range 20-7E with exception to the double-quote character. 

20 SP    21 !              23 #     24 $     25 %     26 &    27 '
28 (     29 )     2A *     2B +     2C ,     2D -     2E .    2F /
30 0     31 1     32 2     33 3     34 4     35 5     36 6    37 7
38 8     39 9     3A :     3B ;     3C <     3D =     3E >    3F ?
40 @     41 A     42 B     43 C     44 D     45 E     46 F    47 G
48 H     49 I     4A J     4B K     4C L     4D M     4E N    4F O
50 P     51 Q     52 R     53 S     54 T     55 U     56 V    57 W
58 X     59 Y     5A Z     5B [     5C \     5D ]     5E ^    5F _
60 `     61 a     62 b     63 c     64 d     65 e     66 f    67 g
68 h     69 i     6A j     6B k     6C l     6D m     6E n    6F o
70 p     71 q     72 r     73 s     74 t     75 u     76 v    77 w
78 x     79 y     7A z     7B {     7C |     7D }     7E ~

Character fields may be of varying length and will have different rules regarding content.

XML Data Type

W3C XML Definition

Character Range
[2]    Char    ::=    #x9 | #xA | #xD | [#x20-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF]
/* any Unicode character, excluding the surrogate blocks, FFFE, and FFFF. */

Support of special characters is included by using backslash-character combinations as described by the TEXT data type. This is solely for backward compatable support of the older key="value" instruction files and not needed for XML instruction files.

TEXT Data Type

A text data type is equivalent to the CHAR data type with the additional support of special characters included by using backslash-character combinations as shown below: 

    \t = horizontal tab (ASCII hex 09)
    \r = carriage return (ASCII hex 0d)
    \n = newline (platform specific)
    \" = double quote (ASCII hex 22)
    \' = single quote (ASCII hex 27)
    \\ = backslash (ASCII hex 5c)

The quotes are listed here not because they are actually replaced with something but because "backslashing" them prevents them from terminating a data value.

For example, to define the following value: 

    The cow says "Moo"!
you would write the following: 
    KEY="The cow says \"Moo\"!"

BOOL Data Type

A Boolean value can be "y", "Y", "n", or "N".

ADDR Data Type

This field contains only the user@domain portion of the address and should not include a text name (see "To_Name", or "From_Name", or "Reply_Name" for name description part of an email address).

ePriority validates email addresses using the specification provided below. This specification is a subset of the one found in «RFC 2822» (Internet Standard) with restriction of comments, whitespace, and "quoted pairs".

ADDRESS=USER "@" HOST
USER=1*ATEXT *("." 1*ATEXT)
ATEXT= LETTER DIGIT ! # $ % & ' * + - / = ? ^ _ ` { | } ~
HOST=LABEL *("." LABEL)
LABEL=LETTER [ *LDH-DIG-HYP LET-DIG ]
LET-DIG-HYP=LET-DIG | -
LET-DIG=LETTER | DIGIT
LETTER=a-z, A-Z
DIGIT=0-9

  • USER (everything before the "@") must be 1-64 characters in length
  • USER is case sensitive
  • HOST (everything after the "@") must be 1-64 characters in length
  • HOST is not case sensitive - and may be converted to upper or lower case

Regular Expression

The following simple regular expression can be used to validate an email address according to the above specification. Length of the user and host will need to be checked as an additional step. 

$RE_ATEXT  = '[a-zA-Z0-9\!\#\$\%\&\'\*\+\-\/\=\?\^\_\`\{\}\|\~]';
$RE_USER   = $RE_ATEXT . '+(\.' . $RE_ATEXT . ')*';
$RE_LABEL  = '[a-zA-Z]([a-zA-Z0-9\-]*[a-zA-Z0-9])*';
$RE_HOST   = $RE_LABEL . '(\.' . $RE_LABEL . ')+';
$RE_REGEX  = $RE_USER . '\@' . $RE_HOST;