GUI ScreenIO for Windows

 ScreenIO.com


SendMail

This API lets you send email from your programs.

Application notes

Sendmail allows you to send email via any standard SMTP server that is compliant with RFC2821, the Internet email standard.  This includes SMTP servers where authentication is required.

Note that some mail servers may not be fully compliant with this specification or may have requirements not supported by this API, such as Microsoft specific extensions.

The features we support are standard text only, no attachments, no CCs no HTML mail. (We don't prevent you from formatting your message as html, we just don't do it for you). 

This utility is meant to automate the sending of notices, confirmations, and progress reports from your application to any addresses you have on file.  The headers of each message will indicate your GUI ScreenIO serial number, as well as the words "GUI-ScreenIO SMTP API Agent" so that we can throw you under the buss to the authorities who will hunt you down like a dog if you use this facility for sending SPAM.

Your program is responsible for supplying the name of the SMTP server (or its IP address), port number, return address, and recipient address as well as the text of the message.

Optionally, if your server requires authentication in order to send mail you must supply a login and password for logging in to the SMTP server.  We currently support authentication via AUTH LOGIN and AUTH PLAIN.  We try the more common LOGIN method first, if offered by the server, and then we fall back to PLAIN.

Each message can be composed of up to 20,000 characters, with formatting supplied by carriage return/line feed (CR/LF X'0D0A') character pairs designating new lines.  Each line is limited by the Internet standard to 1000 characters.  Failure to put a CRLF pair at then end of lines will cause them to be truncated.

If you use a GUI ScreenIO multi-line text control to collect the message text it will contain paragraphs separated with CR/LF pairs, but the user may make long paragraphs with no intervening CR/LF.  If a paragraph has more than 1000 characters with no imbedded CR/LF pairs, the paragraph will be truncated. Therefore it is wise to count characters between CRLF pairs to make sure truncation does not exist.

If you build your own message in memory we suggest the STRING verb be used to construct lines of text separated by X'0D0A' literals.

Client/Server issues

This API will normally run on the client.  You are responsible for acquiring and supplying the SMTP serve address and port numbers for each user, since remote users will be sending mail through their SMTP server rather than the server's.

To send mail through the server's SMTP server:

     SET WIN32API-EXECUTE-API-ON-SERVER TO TRUE

Files

Files available to copy to your system:

Usage

     COPY WIN32API.
     COPY MAILAPI.


     
* ------------------------: Call the API.
*
     SET FUNC-SENDMAIL TO TRUE.

     CALL 'GSWINAPI' USING WIN32API-PARMS
                           APM-MAIL-PARMS 
                           WIN32API-B 
                           WIN32API-C
                           WIN32API-D
                           WIN32API-E
                           WIN32API-F.

Parameters specific to this function

APM-MAIL-PARMS

This structure contains the complete specifications of everything needed to send the message as well as the message text itself.

Flag Size Description
APM-YOUR-NAME 50 Your name in plain text. 
APM-YOUR-EMAIL 250 Your return email address.  Must be in standard email notation similar to myname@mydomain.com.
APM-SMTP-SERVER 250 This must contain the DNS name of the SMTP server, or its IP address in dotted-quad notation.
APM-PORT 4 Numeric PORT number that the SMTP server listens on. Usually this is 25, but occasionally you will have different values for private Email servers.
APM-TO-NAME 250 Name of the recipient of the email (NOT the email address).  The SendMail function will supply the necessary formatting.
APM-TO-EMAIL 250 The recipient's email address.  The sendmail function will supply the angle brackets <name@domain.com> if necessary, so don't include them.
APM-SUBJECT 250 Subject line of the message.
APM-TEXT 20K The body of the message, and should be formatted into lines as you wish it to appear.  Separate each line with X'0D0A' hexadecimal pairs. 

Take care not to include a single period on a line by itself as that is the RFC2821 designation of end-of-text and will terminate your message. (The SendMail function will supply this terminator - so you don't need to worry about it). 

Internet standards suggest (strongly) that your signature section at the bottom be separated by a line containing dash dash space (-- ).  This assists various email clients in presentation of the message layout.
APM-AUTHENTICATION-SWITCH 1 Use the provided 88 name APM-AUTHENTICATE-DESIRED to set this switch if your SMTP server requires authorization.  This is becoming the standard, and should be used in any application you design.  If the SMTP server does not support PLAIN or LOGIN authorization methods this API will fall back to un-authenticated transmission, so this is generally safe to use anytime you have a login name and password.
APM-AUTHENTICATION-USERID 50 If the above switch is set to indicate that authentication is desired, you must provide the case sensitive Login name (userid).  Typically this is the same as the users POP account name (the portion preceding the @ in their email address).
APM-AUTHENTICATION-PASSWORD 50 If the above switch is set to indicate that authentication is desired, you must provide the case sensitive password.

  WIN32API-PARMS - Used in all GSWINAPI calls

This argument is standard for all CALLs to GSWINAPI. It is used to select the desired API or function, and to return the status of the operation.

WIN32API-RC

Used to return the status of a call to GSWINAPI.  A value of zero is a failure, any other value indicates success.

Recommended usage is to test the 88-level value WIN32API to see if it worked, then to use the text error message to see why it failed.

* ------------------------: If function failed,
*                         :   display the error in a message box.
*
     IF WIN32API-FAILED
       MOVE WIN32API-ERROR-TEXT TO panel-MESSAGE-TEXT
       SET panel-MESSAGE-IN-MESSAGEBOX TO TRUE.

WIN32API-ERROR-CODE

Error code that was returned by Windows.  This is not generally useful unless you have the Windows Platform SDK documentation available to you.

WIN32API-ERROR-TEXT

Plain-text error message that describes why the operation failed.

WIN32API-A through WIN32API-F

The number of these present varies depending on how many arguments are used by the desired function.  These are not used, but must be present because this CALL requires seven arguments.


2000-2006 Norcom, all rights reserved 

TOC

Send feedback to Norcom