Relay Mail 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

In addition to batch email processing, ePriority offers a transactional mailing service via SMTP (Simple Mail Transfer Protocol) Relay. For clients who want to send email based on user website actions or other real-time events, an individual email can be delivered through ePriority with the same ease of use as any mail gateway. ePriority provides the same Delivery Profile features for transactional mail as it does for batch email processing.

Using the ePriority SMTP Relay service is no more difficult than sending a message from your desktop mail client. With minimal setup required, any application can be empowered with transactional email support with extended tracking and scheduling features.

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.

Setup

In order to use the Relay Transaction service, a list of IP addresses (or ranges) from which mail will be delivered must be defined under the associated client account. This list can be updated from the Account Settings page on ePriority.com. Changes to this list will take affect within one hour (propogated to our inbound SMTP service is required).

To better define the exact delivery behavior and features you want applied to your transaction email, profiles can be created from the administration web site and identified during the transactional mailing. A "default" profile is always available, but transactional mail often has different needs from batch deliveries.

Using Mail Relay

Once your IP ranges have been defined, profile(s) have been created, and you have waited at least one hour for changes to propogate, SMTP Relaying may be used.

Relay Transaction

When a client application contacts ePriority SMTP servers to perform a relay mail transaction, it will provide three values:

• MAIL FROM: Usually considered the routing return address, but ePriority uses this as a data transport to receive identification of the client, email, and the Delivery Profile.

  Format of the MAIL FROM value is shown below with optional values in brackets (note the underscores separating all values):

      VERSION _ CID _ CPID _ [ CPID2 _ ] [ CPID3 _ ] PROFILE @relay.epriority.com
  

  VERSION	Allowed: r2, r3 The Relay Mail Service version number. Use version r3 when including multiple CPID fields. Version r2 only supports the CPID field, not CPID2 or CPID3. Later releases may provide new versions
  CID	Your ePriority Client ID.
  CPID	Allowed: a-z, A-Z, 0-9, period, hyphen Length: 1-29 Email identification. Must be unique for every email. Cannot begin with a period or a hyphen.
  CPID2	Same rules as CPID. This value is only allowed in version r3. This value is also optional in version r3. Make sure that an underscore always separates the CPID, CPID2 and CPID3 fields. An empty CPID2 field should be surrounded by 2 underscores: r3 _ CID _ CPID ___ CPID3 _ PROFILE @relay.epriority.com
  CPID3	Same rules as CPID. This value is only allowed in version r3. This value is also optional in version r3. Make sure that an underscore always separates the CPID, CPID2 and CPID3 fields. An empty CPID3 field should be surrounded by 2 underscores: r3 _ CID _ CPID _ CPID2 ___ PROFILE @relay.epriority.com
  PROFILE	Name of the predefined profile established at www.epriority.com. If you have not set up a Profile, a value of "default" can be used

  EXAMPLES:
      r2_1105_1234xyz_default@relay.epriority.com
      r3_1105_1234xyz_abc12345_78236y0b4_default@relay.epriority.com
      r3_1105_1234xyz__78236y0b4_default@relay.epriority.com
      r3_1105_1234xyz_abc12345__default@relay.epriority.com
  

  ePriority uses the Client ID (supplied within the MAIL FROM value) to lookup what IP ranges are permitted to make relay transactions. If the connecting mail delivery agent is not within the defined IP range(s), the MAIL FROM command will be refused and relay delivery will be denied.

• RCPT TO: The recipient's email address

• DATA The email message itself, including message headers (From, To, Subject, etc)

Example

Message Tracking

The CPID supplied in the MAIL FROM value during a relay transaction is used for message tracking. All tracking events are made available in logs (downloadable via FTP) in the exact same manner as our batch submission process. Please read our «Service Overview Guide» to learn more about how to download and process logs.

JavaMail Example

import java.util.*;
import java.io.*;
import javax.mail.*;
import javax.mail.internet.*;
import javax.activation.*;


public class Relay implements Serializable
{
  public static void main( String[] args )
  {
    Message message;
    Multipart multipart;

    String VERSION = "r3";
    String CID     = "1105";
    String ID      = "1234xyz";
    String ID2     = "abc12345";
    String ID3     = "78236y0b4";
    String PROFILE = "default";

    String recipient_address = "recipient@domain.com";
    String sender_address    = "sender@domain.com";

    String body = "This is an example relay transaction message.\r\n\r\n"
                + "ePriority Development Team\r\n";
   
    String smtpHostName = "mta2.epriority.com";

    String smtpFromName = VERSION + "_"
                        + CID     + "_"
                        + ID      + "_"
                        + ID2     + "_"
                        + ID3     + "_"
                        + PROFILE 
                        + "@relay.epriority.com";

    Properties props = new Properties();

    props.put( "mail.smtp.host", smtpHostName );
    props.put( "mail.smtp.from", smtpFromName );
    props.put( "mail.debug", "true" );

    Session session = Session.getDefaultInstance( props, null );

    message = new MimeMessage( session );
    multipart = new MimeMultipart();

    try
    {
      message.setRecipients( Message.RecipientType.TO,
                     InternetAddress.parse( recipient_address, false ) );

      message.setFrom( new InternetAddress( sender_address ) );

      message.setSubject( "Relay Transaction Message" );

      message.setSentDate( new Date() );

      BodyPart messageBodyPart = new MimeBodyPart();

      messageBodyPart.setText( body );

      multipart.addBodyPart( messageBodyPart );

      message.setContent( multipart );

      Transport.send( message );

      System.out.println( "Message sent successfully." );

    }
    catch( Exception ex)
    {
      System.out.println( "Exception caught:  " + ex.getMessage() );
    }

    System.exit(0);
  }
}

Perl Example

#!/lopt/perl/bin/perl

use Net::SMTP;

$RELAY_VERSION  = 'r2';
$CLIENT_ID      = 1105;
$PROFILE_NM     = 'default';
$EMAIL_ID       = 1;

$MAIL_FROM      = $RELAY_VERSION
                . '_'
                . $CLIENT_ID
                . '_'
                . $EMAIL_ID
                . '_'
                . $PROFILE_NM
                . '@relay.epriority.com';

$FROM           = 'returnmail@domain.com';
$FROM_NAME      = 'Customer Support';

$TO             = 'recipient@aol.com';
$TO_NAME        = 'Bob Johnson';


$smtp = Net::SMTP->new('mta2.epriority.com');
$smtp->mail($MAIL_FROM);
$smtp->to($RCPT_TO);

$smtp->data();
$smtp->datasend("From: \"$FROM_NAME\" <$FROM>\n");
$smtp->datasend("To: \"$TO_NAME\" <$TO>\n");
$smtp->datasend("Subject: $SUBJECT\n");
$smtp->datasend("\n");
$smtp->datasend("This is a test message.");
$smtp->dataend();
$smtp->quit;