EM API - Create and Send an Email

Release Date: 12/23/20
Version: 7.0 and Higher

This is a set of API calls introduced after Elliott 6.X.060.  Use them collectively.  They will send out emails through the SMTP or MAPI interface.  Developers who use these API calls do not need to know how SMTP or MAPI work.  The following are the options that you can use with these API calls:  

Screen-Parameters

Required/

Optional

Comment

EM,BG,nn,x

Required

Begin Email Process

·        This is a required first call to begin the process of sending a message.

·        Screen-Column = nn (99 means Quiet mode)

·        x = M in position 10 of Screen-Control means bring up your interactive email client (MAPI or SMTP) before sending the email.

  • Screen Numeric Field = Parent Window handle (opt)
    • Screen Answer = "Y" means display Status Messages on the Parent window’s Status Bar if supplied in Screen-Numeric-Field, or on the main Elliott Status Bar if not supplied (opt).

On output, Screen-Answer = “Y” means you may continue.


EM,FR

EM,TO

Optional

Required

Specify a from address in Screen-Literal

To Address or Name

·        Screen-Literal = Recipient Name or Address

  • At least one email address is required
  • You can execute this API call multiple times to send to multiple recipients.  For MAPI, this is subject to the maximum email addresses allowed (100).

EM,CC

Optional

Carbon Copy (CC) Address or Name

·        Screen-Literal = CC Recipient Name or Address

  • You can execute this API call multiple times.  For MAPI, it is subject to the maximum email addresses allowed.

EM,BC

Optional

Blind Carbon Copy(BCC) Address or Name

·        Screen-Literal = BCC Recipient Name or Address

·        You execute this API call multiple times.  For MAPI, it is subject to the maximum email addresses allowed.

EM,SB

Optional

Subject

·        Screen-Literal = Subject

EM,AT

Optional

Attached File

·        Screen-Area = Complete Path and File Name

**Note that the path is required and the attached file must exist.

·        Screen-Function-Values = Visible filename (opt)

If this area is used, the name of the file which will be visible to the recipient will be the value here followed by .TXT.

  • For MAPI, it may be called up to 100 times per email

EM,TX

Optional

Text Content of the Body of the Email

·        Screen-Area = Text Line

  • Screen-Area is a 160 bytes area with Screen-Literal making up the first 80 bytes and Screen-Alpha-Field making up the last 80 bytes.
  • Screen-Numeric-Field = number of characters in the line to include.  If Screen-Numeric-Field = Zeroes, the system layer will calculate the length of the text.  If Screen-Numeric-Field = Zeroes and Screen-Area is blank, a new-line character (X”0a”) will be provided.
  • You may call this API multiple times to construct a multi-line email body.
  • The message body cannot exceed 64K.

EM,HF



EM,HP


EM,IN


EM,AB

Optional



Optional


Optional


Optional

Send email in HTML (not text) format.  This parameter generally is not necessary because the presence of "<" in the first position of the email body and "HTML" within the first 100 characters automatically sets the email to HTML mode.


Set the email to be high priority.


Make the email interactive


Abort the Email

  • Abort constructing the current email.  The system will release all resources allocated for the current email that is being constructed.

·        The message and all its characteristics are ignored.

·        Use only after a successful “EM,BG.”  You do not need to use this API if “EM,BG” was not executed successfully.

EM,SE

Required

Send Email Message

·        Returns ‘Y’ in Screen-Answer if the message was successful.  For MAPI, receiving ‘Y’ does not guarantee the email is sent -- it simply indicates that MAPI has accepted the email, (i.e., emails may not send because MAPI may not be able to connect to the email transport server).

o    Screen-Numeric-Field will contain 0 if the message was sent; 1 if the message was cancelled by the user.

  • Return ‘N’ in Screen-Answer if the message was not successful
    • Screen-Numeric-Field will contain an error code
    • Screen-Literal will contain an error message.

EM,EX







EM,VE

Required







Optional

Exit Email and Disconnect from Email Services

·        This does a logoff from the mail system.

·        This is automatically called by Elliott at shutdown.

  • Follow this call with Cancel “NWSMMAPI” or Cancel "NWSMSMTP."
  • When using MAPI, since the login process may be time consuming in certain environments, you may not want to call this API until all emails are sent.  However, you should make this call as soon as possible after you are done sending emails.
Verify email address in Screen-Alpha-Field.  Screen-Answer will return "Y" if the email address is in proper format.

This call is used outside of the sending-email sequence of calls.

 

Example:

MOVE “EM,BG” TO SCREEN-PARAMETERS.
PERFORM SCREEN-ROUTINE.
IF SCREEN-ANSWER = “N”
      PERFORM NO-MAPI-SUPPORT-MSG
      EXIT PARAGRAPH
END-IF.
 
MOVE “EM,TO” TO SCREEN-PARAMETERS.
MOVE “sales@netcellent.com” TO SCREEN-ALPHA-FIELD.
PERFORM SCREEN-ROUTINE.
 
MOVE “EM,SB” TO SCREEN-PARAMETERS.
MOVE “Sales Promotion” TO SCREEN-LITERAL.
PERFORM SCREEN-ROUTINE.
 
MOVE “EM,TX” TO SCREEN-PARAMETERS.
MOVE “Dear Business Partner:” TO SCREEN-AREA.
PERFORM SCREEN-ROUTINE.
 
MOVE “EM,TX” TO SCREEN-PARAMETERS.
MOVE “There’s a sales promotion going on at Netcellent.”
TO SCREEN-AREA.
PERFORM SCREEN-ROUTINE.
 
MOVE “EM,SE” TO SCREEN-PARAMETERS.
PERFORM SCREEN-ROUTINE.
IF SCREEN-ANSWER = “Y”
      PERFORM MESSAGE-SENT
ELSE
      PERFORM MESSAGE-NOT-SENT
END-IF.

 If you need more examples of source code, please contact Netcellent. “EL800MAIL.CBL” can be provided to Netcellent’s developers with more detail to show you how to construct your own email program.

Error Handling

Any invalid email API calls will result in a message box on the screen and ‘N’ in the SCREEN-ANSWER field.  However, the process will continue.  For example, specifying too many recipients will result in a message box display, but the message may still be sent with the EM,SE call.

Depending on your situation, it might by desirable for you to write your code to check if SCREEN-ANWSER is equal to  ‘N’ to determine if the situation needs special handling by the code.

Setting Email Values While Printing

It is possible to manipulate the values of an email message during the process of sending print lines to the output file, assuming that the output is destined for an email message.

To change an email value, do the following: 

·        Add the following COPY statements to your program:

      Copy SetEmail.WS.
      Copy SetEmail.PL.

·        MOVE  a value type as follows  TO  DETAIL-LINE:

TO

A primary recipient

CC

A carbon copy recipient

BC

A blind carbon copy recipient

SB

The subject line

TX

A line of text in the message body


·       
MOVE    the value itself    TO    DETAIL-LINE(4:)

·        PERFORM SET-EMAIL-OPTION

Notes

  1. You may specify as many TO, CC, and BC values as you wish.
  2. The presence of any TO, CC or BC value means that all the original recipients will be replaced by the new recipient(s).
  3. You may specify as many TX values as you wish.  Each value will be followed by a CR/LF.
  4. The presence of any TX value means that all the original text in the message body will be replaced by the new text.
  5. The SET-EMAIL-OPTION paragraph will MOVE SPACES TO DETAIL-LINE after calling PRINT30 or PRINT240.
  6. If the user specifies output should go to the printer or to disk, these COBOL statements will be ignored.

JEG

Feedback and Knowledge Base