Transaction Service Guide May 7, 2013 PUBLIC DISTRIBUTION DST Systems Electronic Solutions Division 333 W 11th St Kansas City, MO 64105 www.dstsystems.com ePriority Development www.epriority.com

Contents

Introduction

The Transaction Service may be used to send transaction (individual) emails through ePriority via HTTPS. It is not intended for batch or multiple email submission.

To simplify interface requirements the same XML Instruction Format is used for Transaction Service emails that is used for Batch Service emails. Transaction emails sent through this service may utilize all the same tracking and features as our Batch Email Service. Errors may occur when bad credentials are supplied or incorrect/incomplete data is given in the XML Instructions.

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.

HTTP Query

To request a report through an HTTPS query, the following parameters must be supplied:

Authentication

The cid (ePriority Client ID), authDate and authHash parameters are required for authentication of all Web API requests. See authentication instructions.

Using the Transaction Service

It is recommended that a POST request is submitted but GET requests are also honored. Please URL-Encode the XML instructions and specify the correct character encoding in the XML declaration of the instructions. It is a common error to declare in the declaration when in fact the encoding is Windows-1252 or ISO-8859-1.

Outputs

The XML output is defined by the Transaction Service XML Schema.

HTTP response 403 (forbidden) is returned when authentication fails.

HTTPS requests are limited to 10MB. HTTP response 500 (form too large) is returned if your POST exceeds 10MB. Larger emails are allowed through the Batch Service but it is not recommended as 10MB is a standard maximum email size across many ISPs.

Successfull Transaction

<?xml version="1.0" encoding="ISO-8859-1"?>
<transaction xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:noNamespaceSchemaLocation="www.epriority.com/remote/transactionservice.xsd">
  <email>
    <received>true</received>
    <description />
    <pid>1</pid>
    <cpid>3478</cpid>
    <cpid2 />
    <cpid3 />
  </email>
</transaction>

Unsuccessful Transaction

<?xml version="1.0" encoding="ISO-8859-1"?>
<transaction xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:noNamespaceSchemaLocation="www.epriority.com/remote/transactionservice.xsd">
  <email>
    <received>false</received>
    <description>XML Instruction Error: XML error at line 21, column 56:
      cvc-complex-type.2.4.a: Invalid content was found starting with element 'rcp'.
      One of '{rcpt}' is expected.</description>
    <pid>0</pid>
    <cpid />
    <cpid2 />
    <cpid3 />
  </email>
</transaction>

<?xml version="1.0" encoding="ISO-8859-1"?>
<transaction xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:noNamespaceSchemaLocation="www.epriority.com/remote/transactionservice.xsd">
  <email>
    <received>false</received>
    <description>Could not connect to SMTP host: smtp.epriority.com, port: 25;
       nested exception is: java.net.ConnectException: Connection refused</description>
    <pid>1</pid>
    <cpid>3478</cpid>
    <cpid2 />
    <cpid3 />
  </email>
</transaction>

Java Example

import java.io.*;
import java.net.*;
import java.text.*;
import java.util.*;
import java.security.MessageDigest;
import javax.net.ssl.*;

public class EpriorityTransaction
{
  static int myAccountId = 12345;

  // Usage: java EpriorityTransaction myPassword test.xml
  public static void main (String[] args)
  {
    try
    {
      // Prepare Authentication Credentials
      SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss");
      sdf.setTimeZone(TimeZone.getTimeZone("Universal"));
      String authDate = sdf.format(new Date());
      String webServicePw = args[0];
      String digestString = authDate + webServicePw;
      MessageDigest md = MessageDigest.getInstance("SHA256");
      byte[] hash = md.digest( digestString.getBytes() );
      String hashHex = asHex( hash );


      // Prepare Content
      StringBuffer content = new StringBuffer();
      content.append("version=1");
      content.append("&cid=");
      content.append(myAccountId);
      content.append("&authDate=");
      content.append(authDate);
      content.append("&authHash=");
      content.append(hashHex);
      content.append("&instructions=");

      String instructionFile = args[1];
      FileReader reader = new FileReader(instructionFile);
      int ch;
      StringBuffer inbuff = new StringBuffer();
      while ((ch = reader.read()) != -1)
      {
        inbuff.append((char) ch);
      }
      content.append(URLEncoder.encode(inbuff.toString(), "ISO-8859-1"));
      reader.close();


      // Connect to URL
      URL url = new URL ("https://www.epriority.com/TransactionMailer");

      URLConnection urlConn = url.openConnection();
      urlConn.setDoInput(true);
      urlConn.setDoOutput(true);
      urlConn.setUseCaches(false);
      urlConn.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");


      // Send POST output.
      OutputStreamWriter output = new OutputStreamWriter(urlConn.getOutputStream());
      output.write(content.toString());
      output.flush ();
      output.close ();


      // Read XML Response
      BufferedReader input = new BufferedReader(new InputStreamReader(urlConn.getInputStream()));
      String str;
      while (null != ((str = input.readLine())))
      {
        System.out.println(str);
      }
      input.close ();
    }
    catch (Exception e)
    {
      System.out.println(e.getMessage());
    }
  }

  public static final String asHex(byte[] data)
  {
    //double size, two bytes (hex range) for one byte
    StringBuffer buf = new StringBuffer(data.length * 2);

    for (int i = 0; i < data.length; i++)
    {
      //don't forget the second hex digit
      if (((int) data[i] & 0xff) < 0x10)
      {
        buf.append("0");
      }

      buf.append(Long.toString((int) data[i] & 0xff, 16));
    }

    return buf.toString();
  }

}