SendMail

Description

The SendMail object allows your APLX applications to send e-mail messages, using the SMTP protocol supported by most Internet Service Providers (ISPs). It complements the GetMail object, which can be used to retrieve incoming e-mails in your APLX application.

You can use the SendMail object for a number of purposes. For example, you might have an APLX application which automatically analyses some data on a regular basis, and e-mails the results to a list of recipients. Or you might use it as part of an APL-based mailing list application. You can also use it to e-mail automatically-generated diagnostic reports to software-support staff.

Caution: The ability to send e-mails automatically from APLX is very powerful, but you should be very careful not to abuse it by violating privacy or sending out unsolicited 'spam' e-mails to people who do not want to receive them. Not only is this objectionable to many people, it is almost certainly not permitted by your Internet Service Provider and could result in your internet account being terminated. In addition, in many jurisdictions it may be illegal.

Connecting to the SMTP server

The SendMail object should be created as a top-level object, i.e. not as the child of a Window or other control. You then need set up the following properties, to define the address of the SMTP mail server you are using, your username and password (if required). This information should be available from your ISP or network administrator:

host: This is a character vector, to which you should assign the Internet address of the SMTP server. It can be specified either as a domain name (such as 'smtp.myisp.com'), or directly as an internet node address (such as '168.9.211.53').

port: You can use this property to change the port used by the SMTP connection. For most applications you should leave this set to the default value of 25.

user: The user name for the account, if required, should be assigned to this property. (Not currently supported under MacOS.)

password: The password, if required for this account, should be assigned to this property. Not all ISPs require a password for sending mail, in which case you can leave this property as an empty vector. (Not currently supported under MacOS.)

Next, you need to call the Open method, which establishes the connection with the server. (Note: Whilst you have this connection open, you are tying up resources on the server. You should aim to close the connection as soon as you can; if you fail to do so, the SMTP server will eventually time out and close the connection automatically). The Open method returns an integer scalar, which indicates whether the connection succeeded. The returned value will be one of 0 = OK, 1 = Could not find host, 2 = Authentication error (i.e. incorrect username or password), 3 = Other error.

For example:

      SM←'⎕' ⎕NEW 'SendMail'
      SM.host←'smtp.supernet.com'
      SM.user←'microapl'
      SM.password←'sesame'
      SM.Open
0

Preparing the e-mail

Before sending an e-mail, you need to set it up by assigning values to the following properties of the SendMail object:

subject: The subject of the e-mail, as a character vector.

from: The e-mail address of the sender of the e-mail, as a character vector.

to: The recipients of the e-mail, specified as a comma-delimited list of e-mail addresses.

cc: The list of e-mail addresses to which the message should be 'carbon-copied', specified as a comma-delimited list. Leave this as an empty vector if you do not want the e-mail to be copied to people than the main recipients.

bcc: The same as cc, except that the list of recipients will not be shown on the e-mail sent out ('blind carbon copy').

replyto: The e-mail address to which any reply to an e-mail should be sent. It is a simple character vector. If you do not specify this, the 'from' address will be used.

body: The main text of the e-mail, as a simple character vector with carriage return (⎕R) characters separating paragraphs.

attachments: A list of the names of the files (if any) which you want to attach to the e-mail. You should provide full paths for these. You can specify them either as a nested vector of vectors, or as a character matrix, or as a CR-delimited simple character vector. (If you read back the property, APLX always returns the nested vector form). Leave this property as an empty vector if there are no attachments.

Sending the e-mail

Once you have set up the properties of the e-mail, you send it by calling the SendMessage method (you must be connected to the SMTP server to do this). This method takes no argument; it returns an error code as follows: 0 = No error, 1 = Host not found, 2 = Authentication error, 3 = General or comms error, 4 = Attachment not found, 5 = Incomplete header (e.g. 'to' property not set), 6 = Recipient not found.

For example, assuming you have created a SendMail object 'SM' and successfully connected to the server, the following APLX statements would send an e-mail, with an attachment, to MicroAPL:

      SM.to←'microapl@microapl.co.uk'
      SM.from←'bob3@yahoo.com'
      SM.subject←'APLX feedback'
      SM.attachments←'c:\docs\APLXReview.doc'
      SM.body←'APLX is fantastic! See attached review.',⎕R,'Thanks. Bob'
      errcode←SM.SendMessage

Sending another e-mail

Once you have called the SendMessage method to send the e-mail, you can then write new values to the various properties, and send another message. To reset all the properties to their default (empty) values before assigning new values, call the Clear method; this is usually recommended to avoid accidentally retaining some parts of the previous message (such as an attachment). In some cases, however, you may want to send out variants of the same message, in which you can simply change those properties which are different, without calling Clear.

Closing the connection

Finally, you should call the Close method to terminate the SMTP session and free resources on the mail server.

Error reporting and diagnostics

If an error occurs when calling the SendMessage method, an APL I/O ERROR will be generated. If an error occurs when the connection is being established using the Open method, it will return a non-zero result, as described above. In either case, you can use the status property to find out more about the error. This returns a two-element integer vector. The first element is 1 if the connection to the SMTP server is active, else 0. The second element is the latest error code returned by the underlying operating-system networking code. (See for example, the Windows documentation and include file 'winsock.h' for details on these error codes.)

Another useful diagostic tool is the serverreply property. This returns a character vector containing the status message which the server sent back after a call to SendMessage or Open. Usually it will begin "+OK..." to indicate success, but if there is a problem (for example, if the mailbox is already locked) it will contain an error message. This can comprise several lines, separated by carriage returns.

Other

timeout: This is an integer scalar property, which allows you to set the timeout for mail operations, in milliseconds.

Example

     ∇DEMO_SendMail;host;user;password;address;errcode;SM;⎕IO
[1]   ⍝ Sample function demonstrating use of the SendMail object
[2]   ⍝ To run this function, you need an Internet account with
[3]   ⍝ an SMTP mail server, and you need to know the host name,
[4]   ⍝ user name and password (if required) for this account.
[5]   ⍝
[6]   ⍝ Ask the user for the mail account details
[7]   ⍞←'Enter mail server (SMTP) host name: ' ⋄ host←⎕DBR ⍞
[8]   ⍞←'Enter user name:                    ' ⋄ user←⎕DBR ⍞
[9]   ⍞←'Enter password (if required):       ' ⋄ password←⎕DBR ⍞
[10]  ⍞←'Enter your e-mail address:          ' ⋄ address←⎕DBR ⍞
[11]  ⍝
[12]  ⍝ Create the SendMail object and set up connection details
[13]  SM←'⎕' ⎕NEW 'SendMail'
[14]  SM.host←host ⋄ SM.user←user ⋄ SM.password←password
[15]  ⍝
[16]  ⍝ Open the connection to the SMTP server
[17]  errcode←SM.Open
[18]  :If errcode≠0
[19]    :Select errcode
[20]    :Case 1
[21]      'Could not find host'
[22]    :Case 2
[23]      'Authentication error'
[24]    :Else
[25]      'Comms error, error code = ',⍕1↓SM.status
[26]    :EndSelect
[27]    :Return
[28]  :EndIf
[29]  ⍝
[30]  ⍝
[31]  ⍝ Set up the e-mail properties. We'll send an email back to ourselves
[32]  SM.to←address
[33]  SM.from←address
[34]  SM.subject←'Test message: Using the SendMail object'
[35]  SM.body←('APLX is fantastic!',⎕R,'Thanks.')
[36]  errcode←SM.SendMessage
[37]  :If errcode≠0
[38]    'Error ',(⍕errcode),' - message not sent'
[39]  :EndIf
[40]  ⍝
[41]  ⍝ Close connection and clean up
[42]  SM.Close
     ∇

Properties

attachments bcc body cc children class data events from host methods name opened port properties replyto self status subject tie timeout to user

Methods

Clear Close Create Delete New Open Send Sendmessage Set Trigger

Callbacks

onClose onDestroy onOpen onSend

Licensing (Windows and Linux versions)

In the Windows and Linux versions of APLX, the SendMail object is based on the Indy networking classes. The following notices apply to these versions:

Portions of this software are Copyright (c) 1993 - 2003, Chad Z. Hower (Kudzu) and the Indy Pit Crew - http://www.IndyProject.org/.

THIS SOFTWARE IS PROVIDED BY Chad Z. Hower (Kudzu) and the Indy Pit Crew "AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.