How to link cc:Mail and EasyLink
=========================

The following documentation provides instructions on exchanging
mail with EasyLink using cc:Mail Router version 5.1 or greater. 
This version of cc:Mail Router does not require the purchase of 
the separate cc:Mail EZlink product.

cc:Mail Router enables cc:Mail users to exchange messages on 
their LANs with EasyLink or telex users, and access the AT&T 
facsimile and telex services.  

Messages from cc:Mail users to EasyLink users are handled in the
following manner:

1.      The messages are stored in a dedicated mailbox in a
        cc:Mail post office waiting for a connection with EasyLink.  

2.      Cc:Mails' ROUTER program, running on a PC with a modem and
        telephone line, connects to the EasyLink network.

3.      The cc:Mail messages are forwarded to EasyLink.

Messages from EasyLink users to a cc:Mail post office are handled 
in the following manner:

1.      The EasyLink messages are stored in a special EasyLink 
        mailbox.

2.      The cc:Mail ROUTER program connects to EasyLink and exchanges
        the messages.

3.      The messages are forwarded to the cc:Mail recipients. 


cc:Mail Router is designed to operate on an IBM(R) PC, or a compatible
computer.  Lotus cc:Mail recommends the following hardware and software 
to run cc:Mail Router.


Hardware requirements:

        o IBM PC/XT/AT, PS/2, or a compatible computer
        o 380KB of available RAM (for DOS Router)
        o Hayes-compatible modem

Software requirements:

        o cc:Mail Desktop (previously known as LAN Platform Pack)
        o cc:Mail Router Release 5.1 or later (DOS or OS/2)
        o MS-DOS or PC-DOS Release 3.1 or later releases (for DOS Router)
        o OS/2 Release 1.3 or later releases (for OS/2 Router)

EasyLink System Requirements:

        o EasyLink login information (i.e., user ID, password)
        o Dial-up telephone number for EasyLink


What Are the Important Concepts and Terms?
==========================================

Describing an EasyLink Message

An EasyLink message is the basic unit of communication in EasyLink.  
The message corresponds to the cc:Mail message.  Messages are exchanged 
between all users of a cc:Mail post office and EasyLink users the same
way standard EasyLink or telex users exchange messages.  EasyLink 
does not support sending or receiving attachments.

Describing an EasyLink Mailbox

The EasyLink mailbox is an EasyLink userid that is a temporary
repository for messages on the EasyLink system.  The mailbox 

        o stores EasyLink messages sent to cc:Mail users until
          cc:Mail EZlink calls to download the messages to a LAN.

        o receives messages from cc:Mail.

        o forwards the received messages to the specified EasyLink
          users.

Obtain the required EasyLink login information as well as the 
dial-up access number(s) from the EasyLink account representative
that set up your EasyLink account.

Using a Script with cc:Mail Router

The script is an ASCII text file. The cc:Mail Router uses this
file once the dial-up connection has been established to provide
the login information necessary to successfully interact with
the EasyLink login interface, invoke the exchange of messages,
and then exit the EasyLink system.

A sample script is included in this document. See "How Do I Build
the EasyLink Script" section below. Remember this is a sample and
modification may be necessary to exchange mail using your EasyLink
account.

How Do I Build the EasyLink Script?
===================================

Building the EasyLink Script

EasyLink is serviced by a communications network (AT&T). The 
dial-up lines to this network are designed to be accessed by a
person interacting with a series of prompts. cc:Mail Router
allows you to automate this process by using a script file.

cc:Mail script files are made up of 3 components that allow this
interaction to occur and make it easy for the user to customize.

1.      The first field in the script is reserved for the time 
        interval in seconds. The number of seconds indicated must 
        expire before the next fields will be evaluated or acted upon.

        You may need to modify this field depending on the speed of
        your modem connection to the network.

2.      The second field in the script is ignored and used only as a
        place holder unless "Exact Prompt Matching" is turned on.
        This is done using the cc:Mail keywords "PROMPT ON" that 
        indicate to cc:Mail Router to look for exact matching of the
        text in the second field of the script before the next field
        will be evaluated or acted upon. This means that the text must
        match the text that EasyLink is using to prompt you for login 
        information.

        Exact prompt matching can be turned off using the cc:Mail
        keywords "PROMPT OFF" to cause the second field in the
        script to no longer be taken literally and simply treated as
        a place holder.

        If you are using exact prompt matching and you receive the
        cc:Mail error "prompt string not matched", then you may want
        to manually dial the network using a communication 
        application that allows manual interaction. This will allow
        you to verify the text that EasyLink is using to prompt you
        for information, and then identify the discrepency in the
        script file. 

3.      The third field in the script file is reserved for two
        purposes.

        First, it is used to hold the characters that you want sent
        to the interface. For example you can place your login 
        information followed by the control character that represents
        the carriage return (^m) required by EasyLink in this field.
        This is what will be sent as a response to one of EasyLink's
        prompts, equivalent to typing your login information and 
        pressing the carriage return on your keyboard.

        Secondly, it is also reserved for cc:Mail keywords. Keywords
        are recognized by cc:Mail Router as a special command that 
        indicates a task must be performed. A full reference of 
        cc:Mail keywords and descriptions of their associated tasks
        can be found in the cc:Mail Router documentation.

        Keywords specific for use with EasyLink follow:

        DIAL                    Sends Hayes reset and then ATDT followed by 
                                dial-up phone number found in the address
                                field of the EasyLink post office entry.

        USERID                  Obtains the userid from the address of the
                                EasyLink post office entry and sends to the
                                EasyLink interface.
 
        PASSWORD                Obtains the password from the address of the 
                                EasyLink post office entry and sends to the
                                EasyLink interface.

        EZLINK                  Invokes the message exchange with EasyLink.

Within a script line, control characters are represented in
standard Ctrl-key format with the carat character (^)
representing the Ctrl key as follows:

        Control Character       Indicates

        ^m                      a carriage return

        ^@                      do not wait for a return line feed
                                from the system

Using the Sample Script File

The script file in this document is a sample communications
network script for instructing cc:Mail Router how to access the
EasyLink system. Modify the sample script file in the following
way:

1.      Rename the script file with the first eight characters of the
        EasyLink post office name you entered in the cc:Mail
        Directory (for example, EASYLINK). Place this file in the
        directory that contains the cc:Mail Router executable.

        Of if you prefer to have the script file name unique, you may
        do so by specifying "/s=filename" in the address field of the
        Telemail post office entry.

cc:Mail EZlink also creates a temporary file when exchanging messages 
with an EasyLink mailbox.  This file, named GATELINK.EXP, is created 
in the current directory.  The current directory must have sufficient 
free disk space when running the cc:Mail ROUTER program to temporarily 
store the EasyLink messages as they are received.

The following sample script is suitable for standard EasyLink users.
Each line of the sample script is explained in detail.  

1 zzz DIAL
PROMPT ON
5 ID?^q 29 USERID PASSWORD^m^@
10 PTS^m^j^q CANCEL MODE^m^@
10 PTS^m^j^q EZLINK
PROMPT OFF
1 zzz QUIT^m

        o The script in line 1 tells the router to wait 1 second;
          then, the key word DIAL sends the Hayes(TM) command
          Attention Dial Tone (ATDT) and the phone number from the
          address field of the EasyLink post office entry to the 
          modem.

        o The script in line 2 turns on exact prompt matching.

        o The script in line 3 tells the router to wait a maximum of
          5 seconds for the prompt "ID?^q"; then, send system
          identification type 29, the EasyLink userid (obtained from
          the address field of the EasyLink post office entry), and
          your EasyLink password. 

        o The script in line 4 tells the router to wait a maximum of
          10 seconds for the prompt "PTS^m^j^q"; then send the command
          to set CANCEL MODE as the message mode, and then execute
          another carriage return.

        o The script in lLine 5 tells the router to wait a maximum of
          10 seconds for the prompt "PTS^m^j^q"; then initialize
          cc:Mail EZlink code and connect to the EasyLink network.

        o The script in line 6 turns off exact prompt matching.

        o The script in line 7 tells the router to wait a maximum of
          1 second for the prompt "PTS^m^j^q"; then it send the
          command QUIT to the EasyLink interface to end the session.

Using EasyLink Address Modes

Cancel Mode and Cancel Message Mode are the two EasyLink address
modes used by cc:Mail EZlink.  This is how you use them:

        Cancel Mode
        If the address contains an error, EasyLink only cancels 
        the message to that address and sends a cancellation notice,
        which includes an explanation of why the message was
        cancelled.

        Cancel Message Mode
        All addresses in a multiple address message are cancelled
        even if only one of them contains an error.  EasyLink cancels
        all the messages and sends a cancellation notice to the 
        cc:Mail administrator who can forward it to the message
        originator.  

To cancel a set of multiple address messages when only one has
an addressing error, change the script's second line to read as
follows:

        20 PTS^m^j^q CANCEL MESSAGE MODE^m


How Do I Get Started Right Away?
================================

Setting Up the EasyLink Mailbox Userid 

Have an EasyLink representative create a new userid on the
EasyLink system to be the interface with the cc:Mail post office
on the LAN. Also, obtain the EasyLink local telephone-access
number. Record the login information and telephone number for
later use.

Typical EasyLink Login Information

Your EasyLink Userid usually starts with an "ei" 
(e.g., "eic089211"). A mnemonic and password are usually required
after the "ei" ID number and are separated by a period 
(e.g., "name.pass").

Adding EasyLink as a Post Office in the cc:Mail Directory 

Add a name for the EasyLink system in the cc:Mail Directory
with the cc:Mail ADMIN program.  This does not have to be the same
name as the EasyLink userid.  To add EasyLink as a post office in the
cc:Mail Directory, follow the same procedure you use when you add other
post offices. 

A typical cc:Mail EZlink directory entry is as follows:

Name            Loc     Address                 ID       Mnemonic
EasyLink        P       EZLINK 9,1-800-555-1111 ei089211 name.pass

The address must contain the key word EZLINK and must be followed by
the phone number to connect you to the EasyLink network.

If you use the keywords USERID and PASSWORD in the script file, 
then you need to follow the EasyLink network phone number with
the "ei" ID number and then the mnemonic and password as in the 
example above.

NOTE:

You can replace the keywords USERID and PASSWORD in the script
file with the actual login information. The login information
would then not be required in the address field of the EasyLink
post office entry.

Adding EasyLink Users to the cc:Mail Directory

This section applies only if you want to include the names of
EasyLink users in your cc:Mail Directory.  Methods of addressing
messages to EasyLink users who are not contained in the cc:Mail
Directory are described in the section "Sending and Receiving 
Messages Using cc:Mail."  

There are two ways to add the names of EasyLink users to the 
cc:Mail Directory. The first way to add names involves:

1.      Add the actual userids of the EasyLink users as remote
        user names in the cc:Mail Directory.   

2.      Add the name of the EasyLink post office for the corresponding 
        cc:Mail address. 

        This is the same procedure as for any other user on a remote
        post office. 

        This entry would be similar to the following example:

                Name            Loc             Address
                EI9999          r               EASYLINK

The second way to add names involves:

1.      Add a preferred name for the EasyLink user in the mail Directory 
        that is different from the EasyLink userid.  

2.      Add the EasyLink userids following the name of the EasyLink 
        post office that was entered as the cc:Mail address. 

        This second alternative is useful when an EasyLink userid
        does not correspond closely to the user's real name or when
        the full name is desired.  

        See the following example of an entry:

                Name            Loc             Address
                Smith, Bob      r               EASYLINK EI9999

In either case, to add the EasyLink user names and cc:Mail addresses 
to the mail Directory, start the cc:Mail ADMIN program and follow the 
same procedure you use when you add users on a remote post office to
the cc:Mail Directory.

If the actual userid of the EasyLink user was entered as the name in
the mail Directory, no additional information is required.  If, however, 
the EasyLink user's real name was added in the mail Directory, enter 
the person's userid to the cc:Mail address following the EasyLink 
post office name (for example, EASYLINK 62123456).  The userid may be 
an EasyLink mailbox number or a telex address.  

If the cc:Mail address is a telex number, it may include an answerback 
code written in parenthesis following the address number.  Answerback 
is a code associated with the receiving terminal.  EasyLink compares 
the receiving terminal's answerback code with the one entered in the 
address to make sure it reached the correct terminal before delivering 
the message.  Typical examples of a telex address and facsimile terminal 
number are shown below.  

        A telex address might look like  

                765432(XYZ CO UD)  

        A facsimile terminal number might look like

                FAX 4153210458

For additional information on addressing EasyLink, facsimile, and telex 
messages, see your EasyLink User Manual.

Adding the EasyLink Post Office Name to the Call List

You need to add the EasyLink post office to the call list for the 
cc:Mail Router, like you would with any other remote post office.  
You can use all the options available for setting the timing and 
parameters of such calls.  Since EasyLink does not call your cc:Mail 
post office, you should set the minimum number of messages queued 
before a connection is attempted to zero.  

The cc:Mail ROUTER program regularly polls the EasyLink system for
messages to be received, even if no messages are queued for sending to
EasyLink.  In addition, you can use the cc:Mail Router express-calling 
option to call EasyLink.  The procedure is identical to that used for
calling any remote cc:Mail post office.

Verifying the Connection Between cc:Mail and EasyLink

Normally the progress of the connection between the cc:Mail post
office and the EasyLink system is not shown on the display screen.  
However, at least for the first time, the progress of the connection 
should be displayed to ensure that the network script file is correct 
and that the connection to the EasyLink system is successful.

The progress of the connection to the EasyLink system may be displayed 
by including the command-line parameter SHOWLOGIN when starting the 
ROUTER program in communication mode.  The SHOWLOGIN parameter works
both when the connection is initiated from the call list and when an
express connection is made.  Once the connection is functioning
smoothly, the SHOWLOGIN parameter can be removed from the command line.

For example, to make an express call to the EasyLink post office, 
EASYLINK, you might use the following command line:

        F:\CCADMIN\ROUTER EASYLINK M:\CCDATA SHOWLOGIN

A sample Router session might appear as follows:

        F:\CCADMIN\ROUTER EASYLINK M:\CCDATA SHOWLOGIN

        Release 5.11 Copyright(c) 1994.  cc:Mail, Inc.  All rights
        reserved.

        Press Esc to terminate cc:Mail ROUTER program.  11/21/94 1:04PM
        Placing call to EasyLink.  Initiating access to EasyLink.

        EASYLINK
        ID?
        62123456  21NOV94  19:17 EST
        PTS
        CANCEL MODE
        0 messages sent.
        0 messages received.
        EASYLINK
        62123456  21NOV94  19:17 EST
        PTS
        QUIT
        11/21/94  1:05PM Hanging up telephone. . . On-hook.


How Do You Send and Receive Messages Using cc:Mail?
===================================================

Preparing and Sending a Message from cc:Mail to EasyLink

Once the EasyLink users are properly added in the cc:Mail Directory, 
preparing and sending a message to EasyLink is exactly the same as 
sending a message to another cc:Mail user.  

If you wish to address EasyLink users who aren't added to the cc:Mail 
Directory, but who are accessible through an EasyLink post office, follow 
the steps for addressing messages to a post office.  See your cc:Mail
user's manual for more information.  

Reading Your Mail

Receiving mail from EasyLink is exactly the same as receiving mail 
from other cc:Mail users except when address errors occur.  EasyLink 
messages are automatically delivered to the cc:Mail administrator 
when

        o the name of a cc:Mail recipient has not been included in a
          To: or cc: field written in the first part of an incoming
          EasyLink message.

        o the name is incorrectly spelled.

        o the name does not exist in the cc:Mail database.

The administrator can then identify the intended recipient and forward
the message.  cc:Mail names are not included in telex messages delivered 
via EasyLink and must be forwarded to the recipient by the administrator.  


What Are the Other cc:Mail EZlink Functions?
============================================

Using the EZlink Automatic Message Log

A copy of every outgoing EZlink message is automatically logged with the
cc:Mail post office administrator whether EasyLink accepts the message 
or cancels it because of an addressing problem.  These messages are 
logged with the EZlink message number as the subject so any undelivered 
message notice can be easily matched with a copy of the message.  (See 
"Address Error Handling.") 

Using Receipt Requested Delivery Notices

When cc:Mail users request a return receipt for a cc:Mail message sent
to an EasyLink user, a copy of the message is sent to the user and the
cc:Mail administrator when cc:Mail EZlink submits the message to
EasyLink.  The return receipt is sent to the cc:Mail administrator
after the message is delivered.  Because the return receipt only
identifies the delivered message with a message number, the message
number must be used to identify the original message and author so the
receipt can be forwarded to the author.

Using Address Error Handling

If cc:Mail EZlink can't immediately deliver a cc:Mail message to the
EasyLink system because the EasyLink recipient userid is invalid, both 
the cc:Mail message author and the administrator receive a copy of the 
message, indicating an addressing error.  The message may be cancelled 
immediately if EasyLink detects an address error as the message is being 
prepared.   

Because it may take up to several hours to deliver a message such as a
cablegram to an overseas address, EasyLink may initially accept and
attempt to transmit the message, only to discover an addressing error 
later.  When you discover an error make sure that

1.      EasyLink cancels the message.

2.      EasyLink sends a cancellation notice to the cc:Mail
        administrator.

3.      The cc:Mail administrator compares the message number on
        the cancellation notice with the message numbers in the
        administrator's EZlink message log to determine the author
        and contents of the cancelled message.

4.      The cc:Mail administrator forwards the cancellation notice and
        the cancelled message to the cc:Mail message author.

Conversely, while sending EasyLink messages to cc:Mail, cc:Mail EZlink
may discover invalid recipients, or no recipients at all, for a message.  
cc:Mail EZlink routes any messages that contain invalid recipients to 
the cc:Mail administrator for action.


What Error Messages Occur?
==========================

The following is an alphabetical listing of all cc:Mail EZlink error 
messages in the format as indicated.

** Error Message
        Likely Causes
                Suggested Solution

** Error in script file line: . . .
        The printed line either lacks the required three fields or the
        first field is non-numeric.
                Edit the script file and correct the line.

** Password not in cc:Mail address.
        There is no EasyLink password in the cc:Mail address for the
        EasyLink post office.
                Run the cc:Mail ADMIN program and correct the post 
                office address.

** Script file . . . cannot be found.
        cc:Mail Router could not find the network script.
                A network script is always required.  It must have a
                name identical to the first eight characters of the
                EasyLink mailbox name and must reside on the same
                drive and directory as cc:Mail Router.

** Userid not in cc:Mail address.
        There is no EasyLink userid in the cc:Mail address for the
        EasyLink post office.
                Run the cc:Mail ADMIN program and correct the post 
                office address.

