3.7.5.40 Mail

LabTalk Object Type:

External Object

Origin provides a DLL named OMail.DLL that allows you to create a Mail command object, which is used to provide basic email functionality. You can create a command object named mail using the following LabTalk script:

Dll -a mail omail;

The script command will associate the omail DLL with the mail Labtalk object.

Origin's mail object contains three subobjects: SMTP, POP and SIMPLESENDER.

SMTP

SMTP provides the functionality of an SMTP client, used for sending mail. It requires an SMTP server whose address must be supplied.

Properties

Property Access Description
Mail.SMTP.Server$ Read/write,
string
The address of an SMTP server.
Mail.SMTP.From$ Read/write,
string
The sender’s email address.
Mail.SMTP.To$ Read/write,
string
The recipent’s email address or full file name with multiple e-mail addresses (one per line).
Mail.SMTP.Cc$ Read/write,
string
The carbon copy recipent’s email address field or full file name with multiple e-mail addresses (one per line).
Mail.SMTP.Bcc$ Read/write,
string
The blind carbon copy recipent’s email address field or full file name with multiple e-mail addresses (one per line).
Mail.SMTP.Timeout Read/write,
numeric
The connection timeout in seconds (default is 5).
Mail.SMTP.Subject$ Read/write,
string
The subject of the email message.
Mail.SMTP.Header$ Read/write,
string
The file name with the full path of a header of the email message (added before message body).
Mail.SMTP.Text$ Read/write,
string vector
Each element is a single line of message body (till CR-LF symbols). The vector can be emptied using the Labtalk command
Mail.SMTP.Text$ #= empty$;
Mail.SMTP.Footer$ Read/write,
string
The file name with the full path of a footer of the email message (added after message body).
Mail.SMTP.Signature$ Read/write,
string
A file name with full path. If specified, the content of this file will be added after in the end of email message body.
Mail.SMTP.Attachment$ Read/write,
string vector
Full pathnames of all the files that should be attached to the message. The vector can be emptied using the Labtalk command
Mail.SMTP.attachment$ #= empty$;
Mail.SMTP.Error Read,
numeric
Indicate error if non-zero.
Mail.SMTP.ErrStr$ Read,
string
Describe (if possible) error with corresponding error code.

Note that for Mail.SMTP.To$, Mail.SMTP.Cc$ and Mail.SMTP.Bcc$, address field first is tested if it is a valid file name (file should exist and have read permission). If so, then it is considered to be e-mail address.

Methods

Method Description
Mail.SMTP.send( ) It sends the message. It returns
  • 0
Succeed in sending the message.
  • -1
General sending error
  • -2
Bad To: address (demo version only)
  • A positive number
Explained by mail.smtp.ErrStr$.

Examples

mail.SMTP.Server$ = "mydomain.com";
mail.SMTP.From$ = "myself@mydomain.com";
mail.SMTP.To$ = "yourself@anotherdomain.com";
mail.SMTP.Cc$ = "C:\ccMailList.txt";
mail.SMTP.Timeout=10;
mail.SMTP.Subject$ = "This is some subject";
mail.SMTP.Header$ = "C:\Header.txt";
mail.SMTP.Text$ #= empty$;   // to empty the vector
mail.SMTP.Text1$ = "This is the message body, line 1";
mail.SMTP.Text2$ = "This is the message body, line 2";
mail.SMTP.Text3$ = "This is the message body, line 3";
mail.SMTP.Text4$ = "This is the message body, line 4";
mail.SMTP.Footer$ = "C:\Footer.txt";
mail.SMTP.Signature$ = "C:\Signature.txt";
mail.SMTP.Attachment$ #= empty$;   // to empty the vector
mail.SMTP.Attachment1$ = "c:\mapath\somefile.opj";
mail.SMTP.Attachment2$ = "d:\anotherpath\anotherfile.txt";
mail.SMTP.Attachment3$ = "e:\abc\def.txt";
if ( mail.SMTP.Send( ) )
{
	type -b "Sending failed!";
}
else
{
	type -b "Sending successful.";
}

POP

POP provides the functionality of a POP3 client, used for retrieving email from a POP3 server. A POP3 server name, username, and password must be supplied.

Note that the subobject is called POP instead of POP3 because MOCA supports enumerated subobjects such that POP3 might be confusing for the 3rd POP object.

Properties

Property Access Description
Mail.POP.Server$ Read/write,
string
The address of a POP3 server.
Mail.POP.UserName$ Read/write,
string
The user name of a user at the POP3 server whose email is being retrieved.
Mail.POP.Password$ Read/write,
string
The user’s password at the POP3 server.
Mail.POP.Path$ Read/write,
string
The full local path used to save the attachments.
Mail. POP.Port Read/write,
numeric
The POP3 port number (default is 110).
Mail.POP.Timeout Read/write,
numeric
The connection timeout (default is 5 seconds).
Mail. POP.LeaveMessage Read/write,
numeric
Set it to 1 to leave a message on server or 0 (default) to delete after retrieve.
Mail.POP.Subject$ Read,
string
The subject of the email message.
Mail.POP.Sender$ Read,
string
The email address of the sender of the mail message.
Mail.POP.Text$ Read,
string vector
The text of the email message. Each element is a single line of message body (till CR-LF symbols).
Mail.POP.Attachment$ Read,
string vector
The full path names of all the files attached to the message. It is filled by the Retrieve( ) method.

Methods

Method Description
Mail.POP.Retrieve(n) It retrieves nth message if it is available and argument n is specified, otherwise retrieves 1st available message. It returns
  • A positive number n
The number of available messages, including the retrieved one. So, if there were 5 available messages, it will return 5, which means that there are still four available messages. Each message is deleted from the server upon retrieval if property LeaveMessage is 0 (default). Then the method can be called repeatedly to retrieve all the messages.
  • 0
No message is available.
  • -1
General mail retrieving failure
  • -2
Could not connect to the server
  • -3
Invalid user name
  • -4
Invalid password
  • -5
Lost connection during transmission
  • -6
Failed to decode attachments, mail will be deleted.
Mail.POP.DeleteAttachments( ) It deletes all the files (attachments) whose names are stored in the array Mail.POP.Attachment$.

Examples

mail.POP.Server$ = "somePOP3server.com";
mail.POP.UserName$ = "myself";
mail.POP.Password$ = "mypassword";
mail.POP.Timeout = 15;
mail.POP.Port = 110;
mail.POP.Path$ = "c:\mymail";
mail.POP.LeaveMessage = 1;
mail.POP.Retrieve(1)=;
type ">>>> After getting mail:";
mail.POP.=;	// dump into the script window the POP object

SIMPLESENDER

It is used for sending mail using an outlook (or other MS-compatible) client. It, therefore, requires a mail client to be properly installed and configured to work. Furthermore, SIMPLESENDER does not support advanced features such as Cc, Bcc and multiple sending, which are present only in SMTP.

Properties

Property Access Description
Mail.SIMPLESENDER.To$ Read/write,
string
The recipient’s email address.
Mail.SIMPLESENDER.Subject$ Read/write,
string
The subject of the email message.
Mail.SIMPLESENDER.Text$ Read/write,
string vector
Each element is a single line of message body (till CR-LF symbols). The vector can be emptied using the Labtalk command
Mail.simplesender.Text$ #= empty$;
Mail.SIMPLESENDER.Attachment$ Read/write,
string vector
Full pathnames of all the files that should be attached to the message. The vector can be emptied using the Labtalk command Mail.
SIMPLESENDER.Attachment$ #= empty$;

Methods

Method Description
Mail.simplesender.Send( ) It sends the message. It returns
  • 0
It succeeds.
  • A negative number
Failed to send the message.

Examples

mail.SIMPLESENDER.Subject$ = "email message subject";
mail.SIMPLESENDER.Text$ #= empty$;   // to empty the vector
mail.SIMPLESENDER.Text1$ = "This is the message body, line 1";
mail.SIMPLESENDER.Text2$ = "This is the message body, line 2";
mail.SIMPLESENDER.Text3$ = "This is the message body, line 3";
mail.SIMPLESENDER.Text4$ = "This is the message body, line 4";
mail.SIMPLESENDER.To$ = " yourself@anotherdomain.com";
mail.SIMPLESENDER.Attachment$ #= empty$;   // empty the attachment list
mail.SIMPLESENDER.Attachment1$ = "c:\mapath\somefile.opj";
mail.SIMPLESENDER.Attachment2$ = "d:\anotherpath\anotherfile.txt";
mail.SIMPLESENDER.Attachment3$ = "e:\abc\def.txt";
mail.SIMPLESENDER.Send();

Other Methods and Properties

Methods

Method Description
Mail.CheckAddress(str) It checks the string for email address type with the following return values.
  • 0
String is empty or not e-mail address.
  • 1
It is a good email address from a real institution.
  • -1
It is one of those free email address like hotmail.com.

Examples

type = mail.checkAddress(%A);


For detailed examples on the mail object, see the example of Email Processing.