TechNote (Archived)

Sending e-mail from Director using the Multiuser Xtra

With the Multiuser Xtra, Director can send e-mail without the need of a third party Xtra or e-mail client. The example Director 7 file available below demonstrates the basic components required to send e-mail using SMTP (Simple Mail Transfer Protocol) and the Multiuser Xtra.

This TechNote is aimed primarily at developers already familiar with the Multiuser Xtra. For a simpler way to send e-mail from Director, please refer to How to send e-mail via Director?, (TechNote 12655). This TechNote discusses one working example of sending e-mail via a standard SMTP server and may may not work on all server types due to differences in SMTP implementation. We recommend fully testing this example with your servers and also researching SMTP implementation for the servers that will be receiving the e-mail.

Note: This is just one of the many ways to create this functionality in Director. This download contains the following file:

	smtpe_mail.dir

Download the Windows zip file
Download the Macintosh sea file

This TechNote is divided into four sections:

Instructions for the included movie
SMTP (Simple Mail Transfer Protocol) overview
Using the Multiuser Xtra to connect to an SMTP server
Troubleshooting

Instructions for the included movie

To send e-mail from the included sample movie, do the following:

Start the movie.
In the "mail server" field, enter the IP address of the server. Check with the server administrator if the IP address is not known.
A typical mail server address could look something like:
"mail.someServer.com"
In the "port" field enter the port number which the server uses to make SMTP connections. Typically this port number is 25. Again, check with the server administrator if unsure of the port number.
In the "mail to" field, enter the recipient's e-mail address.
In the "mail from" field, enter the sender's e-mail address. This address will be used for error reporting (for example, if the server is unable to deliver the message).
In the "subject" field enter the subject of the e-mail message.
Enter the e-mail message in the large scrollable field.

Click the "send e-mail" button.

The following sequence of "Status" messages should appear in the field towards the bottom of the stage:

	"ConnectToNetServer sent to server"
	"ConnectToNetServer successful"
	"HELO message sent to server" (Note: HELO is an SMTP command)
	"MAIL FROM message sent to server" (Note: MAIL FROM is an SMTP command)
	"RCPT TO message sent to server" (Note: RCPT TO is an SMTP command)
	"DATA message sent to server" (Note: DATA is an SMTP command)
	"Message content sent to server"
	"QUIT message sent to server" (Note: QUIT is an SMTP command)
	"Email sent successfully"

For explanations of the above SMTP commands, please refer to theSMTP (Simple Mail Transfer Protocol) overview section.
If errors are encountered, please refer to the Troubleshooting section.

A successful transmission will be indicated by the following message: "Email sent successfully"

SMTP (Simple Mail Transfer Protocol) overview

SMTP is a standardized set of commands used to send, forward, and relay e-mail, and retrieve, expand, and send posts to newsgroups. This TechNote will only focus on the commands required to establish a connection and send e-mail to SMTP servers. However, all SMTP commands can be accessed via the Multiuser Xtra.

For detailed information on SMTP, please refer to Internet Request for Comments 821 (RFC 821).

In order to send e-mail, SMTP requires that the following commands be sent in the following sequence:

Required sequence of SMTP commands:

"HELO"
Used to identify the sender's domain to the server.
If accepted, the server will respond with the number "220" indicating that the connection was initialized.
"MAIL FROM:"
Used to initiate a mail transaction and to designate the sender's e-mail address.
If accepted, the server will respond with the number "250" indicating that the sender is OK.
"RCPT TO:"
Used to specify the address where the mail should be sent.
If accepted, the server will respond with the number "250" indicating that the recipient is OK.
"DATA"
Used to notify the server that the following messages will contain the sender's mail data.
If accepted, the server will respond with the number "354".
Contents of e-mail message, ending with "." on a line by itself.
If accepted, the server will respond with the number "250" indicating that the message was accepted for delivery.
"QUIT"
Used to close the transmission.
If accepted, the server will respond with the number "221" indicating that the connection was closed.

Using the Multiuser Xtra to connect to an SMTP server

When connecting to an SMTP server (or any other text-based server), ConnectToNetServer() must include "1" as the last parameter:

 ConnectToNetServer("String", "String", mailServer, portNumber, movieName, 1)

Note: The userID, password, and subject parameters do not need to be set for SMTP connections. It will be acceptable to leave them set to the string "String".

The server will respond with two consecutive messages:

 [#errorCode: 0, #recipients: ["String"], #senderID: "System", #subject: "ConnectToNetServer", 
		

	 #content: <Null>, #timeStamp: 0] [#errorCode: 0, #recipients: ["String"], #senderID: "mail.someServer.com", #subject: "String", 
		

	 #content: "220 mail.someServer.com ESMTP SendMail 8.9.1 a/8.8.8 Thu, 2 Dec 1999 17:37:10 -0800 (PST)", 
		

	 #timeStamp: 0]

The first message is the standard response to a successful ConnectToNetServer() command. The second message is a typical example of an SMTP response.

It is now possible to continue with SMTP messaging.

Additional Notes:

A message subject (the value of the #subject property) is completely ignored when making text connections. Therefore, it will not be possible to have callback handlers triggered by the #subject of incoming messages.

The included sample movie processes all messages in a callback handler called, "MessageHandler".
SMTP requires that commands end with <CRLF> (a carriage return followed by a line feed). To accomplish this inside a Lingo string, use the numToChar() function to convert the carriage return and line feed ASCII codes.

For the carriage return use:
```
 numToChar(13) 
```
For the line feed use:
```
 numToChar(10) 
```
Also, SMTP may require that the SPACE character be sent. This can be accomplished with:
```
 numToChar(32) 
```

Sequence of Multiuser Xtra messages with SMTP commands (issued once the above ConnectToNetServer() was successful):

 SendNetMessage("String", "String", "HELO"&numToChar(32)&"DomainOfSendersMailService"&numToChar(13)&numToChar(10))

Note: As described earlier, the subject of these messages can be left set to the string "String".

The server will respond with the following message (again, some of the #content text may vary depending on the server configuration):

 [#errorCode: 0, #recipients: ["String"], #senderID: "mail.someServer.com",  #subject: "String", #content: "250 mail.someServer.com HELLO  [IPAddressOfSender], pleased to meet you", #timeStamp: 0]

 SendNetMessage("String", "String", "MAIL FROM:"&numToChar(32)&sendersEmailAddress&numToChar(13)&numToChar(10))

The server will respond with the following message:

 [#errorCode: 0, #recipients: ["String"], #senderID: "mail.someServer.com",  #subject: "String", #content: "250 sendersEmailAddress...  Sender ok", #timeStamp: 0]

 SendNetMessage("String", "String", "RCPT TO:"&numToChar(32)& destinationEmailAddress&numToChar(13)&numToChar(10))

The server will respond with the following message:

 [#errorCode: 0, #recipients: ["String"], #senderID: "mail.someServer.com",  #subject: "String", #content: "250 destinationEmailAddress...  Recipient OK", #timeStamp: 0]

 SendNetMessage("String", "String", "DATA"&numToChar(32)& numToChar(13)&numToChar(10)

The server will respond with the following message:

 [#errorCode: 0, #recipients: ["String"], #senderID: "mail.someServer.com",  #subject: "String", #content: "354 Enter mail, end with "." on a line by itself",  #timeStamp: 0]

 SendNetMessage("String", "String", "Subject: "&emailSubject&numToChar(13)& numToChar(10)&emailData&numToChar(13)&numToChar(10)&"."&numToChar(13)&numToChar(10))

The server will respond with the following message:

 [#errorCode: 0, #recipients: ["String"], #senderID: "mail.someServer.com",  #subject: "String", #content: "250 RAA17753 Message accepted for delivery",  #timeStamp: 0]

 SendNetMessage("String", "String", "QUIT"&numToChar(13)&numToChar(10))

The server will respond with the following two consecutive messages:

 [#errorCode: 0, #recipients: ["String"], #senderID: "mail.someServer.com",  #subject: "String", #content: "221 mail.someServer.com closing connection",  #timeStamp: 0] [#errorCode: -2147216214, #recipients: ["String"], #senderID: "mail.someServer.com", 
		

	 #subject: "ConnectionProblem", #content: "String", #timeStamp: 26444635]

Troubleshooting

Any errors will be reported in the field towards the bottom of the stage.

Common error messages:

"Server Message: 501 HELO requires domain address"
This can occur if an email address is not specified in the "mail from" field.

The SMTP server requires that a sender's domain is specified as part of the HELO message. The solution to the problem is to enter a valid email address in the "mail from" field.

TechNote revised:
2/8/00 - Modified example movie: callback handlers now respond to nothing more than SMTP numerical codes, certain message sequencing is now dictated by the status of the last outgoing message rather than the content string of the current incoming SMTP message, messages are now dumped into a scrolling text field, email subjects can now be specified. Modified TechNote text to accommodate the changes to the movie.