. DirectXtras Home
        Home

DirectCommunication Xtra
DirectConnection Xtra
DirectControl Xtra
DirectEmail Xtra
Documentation
License Agreement
Licensing Fees
Order Form
DirectFTP Xtra
DirectImage Xtra
DirectInteraction Xtra
DirectOS Xtra
DirectSMS Xtra
DirectSound Xtra
DirectTransition Xtra
DirectTransition3D Xtra Set I
DirectTransition3D Xtra Set II
DirectTransition3D Xtra Set III
DirectTTS Xtra
XtrAgent
DirectXport Xtra

SpeechPlugin

Special Discounted Bundles

The Gallery
How To Order
Order Form
Check for Upgrades

Sign in
Change Your Profile

Contact Us
















    .
DirectXtras
Xtra Power for Director & Authorware



DirectEmail Xtra
 The best way to send email through Director!

Authorware 4.x Compatible Authorware 5.x CompatibleAuthorware 6.x CompatibleAuthorware 7.x CompatibleDirector 5.x Compatible Director 6.x CompatibleDirector 7.x Compatible Director 8.x CompatibleDirector MX CompatibleDirector MX 2004 Compatible Director Shockwave Compatible and Safe     MacOS 8.x and 9.x CompatibleMacOS X CompatibleWindows Compatible   

DirectEmail Xtra™ Version 2.1.1 Documentation

 

Developed by Tomer Berda, DirectXtras Inc.
(C) Copyright 1998-2004.
Last updated: August 20th, 2004.

DirectEmail is a cross-platform, easy to use Scripting Xtra for Macromedia Director, Authorware and Shockwave that provides applications with the ability to reliably send e-mails, send faxes as well as validate e-mail addresses.

Emails can be sent in either plain text or rich HTML format, in various languages, and can include file attachments.

DirectEmail Xtra provides applications with the most reliable way to send e-mails. The Xtra does not depend on any other external application and can send e-mails with or without relaying through a mail server as long as there is an active Internet connection.
Furthermore, the Xtra provides applications with precise error information in case of any failure in the e-mail or fax delivery, allowing applications to act appropriately hence insuring that no e-mails or faxes will get lost.

DirectEmail Xtra can send e-mails through a relaying mail server or take on the role of a mail server and deliver e-mails directly to the recipient's email account.

The Xtra is available for Director 5 and above, Authorware 4 and above,  and is compatible with Windows 9X and newer (including 2000, ME, NT, XP) as well as MacOS 8, 9 and X.

DirectEmail Xtra is Shockwave safe and therefore it can also be used with Shockwave 7 or newer and when safety features in Director are turned on.

When the Xtra is in safe mode it can attach files to the e-mail from anywhere in the local machine through a built-in file selection dialog box, or directly from the Shockwave support folder (dswMedia folder) or any other local dswMedia folder without displaying a dialog box.

An auto downloadable Shockwave safe package of DirectEmail Xtra is also available. It is a compressed, small sized (about 30K) version of the Xtra, that can be downloaded automatically from a web site to the user's local machine whenever needed, and once installed provides Shockwave applications on the web with the ability to send e-mails and faxes.

DirectEmail Xtra is fully compliant with RFC 2821 and other related RFCs.

 

Installation

Registration

Overview

Discussion about mail servers

Using DirectEmail Xtra

Sample Code

Sending Faxes

Backward Compatibility Notes

Functions Reference

New()
Forget()

SendEmail()

VerifyEmail()
EmailMode()

EmailPort()
EmailDone()

EmailAbort()

EmailErrorCode()

EmailErrorMessage()

EmailResult()

Error Codes
History

Installation

DirectEmail Xtra has an authoring version, a run time version, and an auto downloadable Shockwave safe package. The trial version only includes the authoring version.

The authoring version is used by Director and/or Authorware authoring environment while developing your movie/presentation. It should be placed in your Director and/or Authorware "Xtras" folder.

The run time version is used when running your movie/presentation as a stand-alone application. It should be placed in a folder named "Xtras" that is inside the folder that contains the host projector/package. Alternatively, the run time version can be bundled in projectors/packages (in a similar way you bundle other Director\Authorware files).

When creating Director projectors please note that if the Xtra is listed in the Modify->Movie->Xtras dialog  then the "Include in Projector" checkbox must be unchecked otherwise Director will bundle the Authoring version of the Xtra in the projector, which will not work outside the authoring environment. Instead, add the run time version of the Xtra in the "Create Projector" dialog or include it in the projector "Xtras" folder.

The run time version is also used with the Authorware web player and can be bundled in the web package. When creating packages in Authorware,  please note that by default, Authorware will attempt to bundle the authoring version of the Xtra. You'd have to modify the application 'Publish Settings' in order to instruct Authorware to bundle the run time version instead of the authoring version.


The auto downloadable Shockwave safe package is used by Shockwave for Director. The package should be uploaded to your server from which it will automatically get downloaded and installed by your Shockwave movie, if needed.

Please note the user may or may not accept the auto downloadable Xtra. If the user does not approve the Xtra installation, script errors may occur if your application attempts to call any of the Xtra functions. In order to avoid script errors we highly recommend checking whether the Xtra is installed prior to calling any of its functions.

The auto downloadable Shockwave safe package consists of the following files:

DirectEmail.w32 - Shockwave safe package for Windows
DirectEmail.ppc - Shockwave safe package for MacOS 8.x and 9.x
DirectEmail.carb - Shockwave safe package for MacOS X

Please note that Director requires that all the above files would be uploaded to your server even if you're only using the Xtra on one platform.

Once you have decided the location on your server where the auto
downloadable packages will be placed, you should modify the "xtrainfo.txt"
file in the Director 7 or above folder accordingly. For example, if you uploaded the downloadable package to "http://www.myserver.com/packs" you should add the following line to "xtrainfo.txt".

[#namePPC:"DirectEmail", #nameW32:"DirectEmail.x32",
#package:"http://www.myserver.com/packs/DirectEmail"] 

Note that the above entry should consist of a single line in the "xtrainfo.txt" file.

Finally, add a reference to the auto downloadable package in your movie.
Open a movie that uses the DirectEmail Xtra. From the
Modify->Movie->Xtras dialog in Director, select the DirectEmail Xtra in the list of Xtras. The "Download if needed" check box should now be enabled. (If it's not enabled, make sure the filename in "xtrainfo.txt" matches the actual filename of the Xtra.) Click on the check box and Director will load information from the package file for each platform and add it to the current movie. 


IMPORTANT: The authoring, run time and Shockwave versions can not coexist in the same "Xtras" folder, so be sure to place the appropriate version in the appropriate folder. 

 

Registration

DirectEmail Xtra is a commercial product. 

Basically, there are 3 types of licenses: Single, Site and Corporate.

Single License: Entitles an organization to receive one copy of the licensed Xtra(s) which can only be used by a single developer on a single computer at any one time.

Site License: Entitles an organization to receive one copy of the licensed Xtra(s) which can be used by any number of developers on any number of workstations within one site.

Corporate License: Entitles an organization to receive one copy of the
licensed Xtra(s) which can be used by any number of developers on any
number of workstations within the entire corporation (multiple sites).

Once you have licensed DirectEmail Xtra, you will be given a serial number. Your DirectEmail Xtra serial number should be passed to the New() function when creating the DirectEmail Xtra instance in order to unlock the trial limitations. Once the Xtra is unlocked, trial warnings will no longer be presented, there will be no other limitations and the run-time and Shockwave versions of the Xtra will become activated.

Be sure to protect the call to New() so that your DirectEmail Xtra serial number would not become exposed to others. This can be done in a similar way you protect the rest of your application source code. If you intend to distribute your application with open source code then pass New() the number 0 as your serial number. This will switch the Xtra into a trial mode and you can instruct developers to change the number 0 with their serial number. Alternatively, you can protect just the appropriate New() calls in your code.

The New() function should be called before any of the other Xtra functions are called. 

You can freely distribute the run time version and Shockwave safe package of DirectEmail with any application developed by you, and you alone. You can not redistribute the authoring version. Please refer to the license agreement for further information.

Note that if your Shockwave movie needs to run on both Windows and MacOS, you'd need to obtain a license for both the Windows and MacOS versions of the Xtra.

 

Overview

DirectEmail Xtra functions are divided into two categories, asynchronous and synchronous.

Synchronous functions return control to Director/Authorware as soon as they complete their task. They return an error code indicating whether their task was completed successfully. All of the synchronous DirectEmail functions return immediately, as they only retrieve information such as error codes, function results, transfer status, etc.

Asynchronous functions return control to Director/Authorware immediately, while continuing to perform their task in the background. They return an error code indicating whether their task was started successfully. Asynchronous functions might fail to create or start the background task if there is not enough free memory available, an invalid parameter was passed or another background task is in progress.

As an example, SendEmail() function is Asynchronous, allowing your application to send e-mails while at the same time perform other tasks, such as playing an animation indicating that an e-mail is being sent, or calling other DirectEmail synchronous functions to track down the transmission status.

Each instance of DirectEmail Xtra can manage one background task at a time. In order to have multiple background tasks at the same time, create multiple instances of DirectEmail Xtra and work with them simultaneously. 

Once DirectEmail asynchronous function succeeds to create a background task, you should frequently call EmailDone() to check its status. When the background task is completed, call EmailErrorCode() to check whether the task was completed successfully, and EmailResult() to obtain further information about the completed task.

 

Discussion About Mail Servers 

There are two ways to send e-mails using DirectEmail Xtra. The first option is through a relaying mail server, and the second option is directly to the recipient's e-mail account, bypassing such a server.

This section discusses the advantages and drawbacks of each method.

Sending e-mails through a relaying mail server

This is the most common method used by mail clients. It is also the fastest and most reliable way to send e-mails. The idea is that the e-mail is sent out through a relaying server. After the server accepts the e-mail, it becomes its responsibility to deliver the e-mail to all recipients. If the e-mail cannot be delivered by the server, the server must send an e-mail to the sender notifying there is a problem.

The relaying mail server is also responsible for queuing e-mails that could not be delivered immediately and retry delivering them again later.

The main advantage of using this method is that your application will have to transfer one copy of the e-mail to the relaying mail server and let it take care of the rest. 

The drawback of this method is that your application must provide the Xtra with an address of a relaying mail server it can relay on. The relaying mail server must also be configured to accept the e-mail as it is sent from your application.

In order to prevent spamming, most mail servers are configured to reject e-mails if they do not recognize the sender and/or recipient e-mail address, or if they were not provided with a user name and password, or even based on the IP address of the sender machine (restrictions may vary from server to server), therefore, it is important that your application will provide the Xtra with a valid mail server address that would accept the e-mail as it is sent from your application.

If you have a relaying mail server that you can use for the purpose of sending e-mails from your application, simply provide its address to the Xtra, and if necessary, login information as well. 

Otherwise, your application can ask the user for his/her mail server address, use it and store it for future uses, in a similar way typical mail clients are doing. However, keep in mind that not all users may know their mail server address, or even have one to use at all.

Important note on ISP restrictions:

Some ISPs adopted a policy where the default SMTP port # 25 is blocked for certain type of accounts, typically for home users, to prevent them from running a mail server locally. This measure also prevents mail clients from relaying through any external mail server via the default SMTP port # 25 except the ISP mail server.

Applications that want to deliver e-mails under this restriction have two options:

1) Send the e-mails through the ISP relaying mail server via the default SMTP port # 25.
2) Send the e-mails through an external relaying mail server but not via the default SMTP port. This requires setting the relaying mail server to listen on a secondary port in addition to port # 25, and it also requires setting the Xtra to send the e-mail through the secondary port by calling the EmailPort() function.

If the Xtra is inadvertently provided with an invalid mail server address or if the provided mail server is inaccessible or rejects the e-mail, an appropriate error code is returned, allowing your application to act appropriately.

If you do not have a mail server that your applications can relay on and prefer not to obtain one from the user for the reasons explained above, but you still want to send e-mails through a relaying mail server to take advantage of the benefits that a relaying mail server provides, you can do so by relaying through DirectXtras mail servers.

For a small monthly fee, DirectXtras can provide a relay through their servers. The relaying server would allow your application to send e-mails from any e-mail account or to any e-mail account without limitations. However, please note that currently the DirectXtras relaying mail server can only accept e-mails through port # 25.

Once you sign up for such an account, also known as DirectSMTP account, you will be provided with a mail server address, user name and password. Your application should pass these values to the New() function when creating the DirectEmail Xtra instance in order to take advantage of the relaying mail server.

Sending e-mails directly to the recipient's e-mail account

By specifying an empty string as the mail server address, the Xtra will attempt to deliver the e-mail directly to the recipient's e-mail account without relaying through a mail server. In other words, it will take the role of a relaying mail server.

The main advantage of this method is that your application will not have to
provide the Xtra with a relaying mail server address, as discussed in the
previous section.

Another advantage is that as soon as the Xtra completes sending an e-mail to the server that hosts that e-mail account, the e-mail will reside in the recipient's mailbox for an immediate retrieval.

There are three drawbacks to this method.

1) It may take more time for the Xtra to deliver the email.

Since each e-mail is being delivered directly to the recipient's e-mail account, the Xtra first has to locate the recipient's mail server that hosts the recipient's e-mail account, connect to it and attempt to deliver there the e-mail. 

If there are other recipients to the e-mail, the Xtra will attempt to use that mail server to deliver the e-mail to the other recipients as well. However, the mail server may reject relaying and as a result will force the Xtra to deliver the e-mail directly to the other recipients.

In example, lets say that your application has to send an e-mail from sender@email.com to recipient1@yyy.com, recipient2@yyy.com and recipient3@zzz.com.

Using this method, the Xtra will first connect to yyy.com and deliver the e-mail to recipient1@yyy.com and recipient2@yyy.com. yyy.com may then reject relaying the e-mail to recipient3@zzz.com, and as a result, the Xtra will then connect to zzz.com and deliver another copy of the e-mail to zzz.com. Therefore, two copies of the e-mail would actually get transferred, one to yyy.com and one to zzz.com.

To summarize, if there are multiple recipients to the e-mail and the recipients e-mail accounts are not located on the same host, it may take the Xtra more time to deliver the e-mails. The process of locating the mail servers that host the recipient e-mail accounts may also increase the overall time it would take the Xtra to send the e-mail.

2) Your application is responsible for error handling

In some cases the Xtra may not be able to deliver the e-mail immediately. For example, when the recipient mail server is down. In other cases, the Xtra may not be able to deliver the e-mail at all, for example, when the recipient e-mail address is invalid and therefore the server that suppose to host such an account could not be found.

In such cases, the Xtra will provide your application with a list of undeliverable recipients along with the errors that have occurred. It is then your application responsibility to either try again later or notify the user, depending on the error and your applications needs.

Applications are encouraged to retry sending e-mails to undeliverable recipients when the error is transient, and discouraged from repeating the exact request when the error is permanent. Error codes between the range of 500 and 600, as well as errors 9104 and 10200 are considered permanent.

When your application sends e-mails through a relaying mail server as discussed in the previous section, the server usually attempts to deliver the e-mail for 5 days if the problem is transient, and warns the sender after a few hours of failed attempts. If the e-mail is undeliverable for any reason, the server notifies the sender via e-mail.

When your application sends e-mails directly to the recipient's email account as discussed in this section, the Xtra will not attempt to handle transient errors as a typical mail server does, allowing you to decide how to handle each case, depending on the error and your application needs.

3) The ISP may not allow this method

Some ISPs adopted a policy where the default SMTP port # 25 is blocked for certain type of accounts, typically for home users, to prevent them from running a mail server locally. This method will not work under such a restriction. Instead, applications should send e-mails through a relaying mail server as explained in the previous chapter.

 

Using DirectEmail Xtra


Following are step by step instructions on how an application can use the Xtra to send e-mails.

The next section summary all steps and includes a complete sample code for sending an e-mail.

Step 1 - Create a new instance of DirectEmail Xtra and store it for a later use. You will have to pass it as the first parameter to the other DirectEmail Xtra functions.

Lingo Sample Code for Director:

When using a relaying mail server:

Set Email = new (Xtra "DirectEmail", "my.mailserver.com", "MyUserName", "MyPassword", 0)

Sample Code for Authorware:

Email:=NewObject("DirectEmail", "my.mailserver.com", "MyUserName", "MyPassword",0)

JavaScript Sample Code for Director:

var Email = new xtra("DirectEmail", "my.mailserver.com",  "MyUserName", "MyPassword", 0)

Where "my.mailserver.com" is the relaying mail server address, "MyUserName" is the server login user name, and "MyPassword" is the server login password. If no user name and password is required, pass an empty string instead.

When not using a relaying mail server:

Lingo Sample Code for Director:

Set Email = new (Xtra "DirectEmail", "", "", "", 0)

Sample Code for Authorware:

Email:=NewObject("DirectEmail", "", "", "",0)

JavaScript Sample Code for Director:

var Email = new xtra("DirectEmail", "",  "", "", 0)

Step 2 - Send an e-mail.

Lingo Sample Code for Director :

Set Result = SendEmail (Email, "from@me.com", "to@you.com", "replyto@me.com", "cc@you.com", "bcc@you.com", "Subject", "Body of the Message", FileToAttach)

Sample Code for Authorware :

Result:=CallObject (Email, "SendEmail", "from@me.com", "to@you.com", "replyto@me.com", "cc@you.com", "bcc@you.com", "Subject", "Body of the Message", FileToAttach)

JavaScript Sample Code for Director :

var Result = Email.sendEmail ("from@me.com","to@you.com","replyto@me.com", "cc@you.com", "bcc@you.com", "Subject", "Body of the Message", FileToAttach)

Where FileToAttach variable is a string containing the pathname of the file  to attach, in the format of "C:\attachment.exe" on Windows and "MyHD:MyFolder:Attachment.hqx" on MacOS. 

Each of the SendEmail() parameters may be an empty string in which case that parameter will be ignored.

Email addresses should be specified in the form of "my@email.com" or
"<my@email.com>" or "My Name (My Title) <my@email.com>"

Multiple addresses and file locations are supported and can be specified separated by commas. For example, to send the e-mail to two different addresses, the third parameter should be modified to "to@you.com,to@youaswell.com".

After calling SendEmail() you should check the value of variable 'Result'. If it is zero, move on to the next step. Otherwise, the value is an error code indicating the error that has occurred. 

Step 3 - Frequently call EmailDone() to check the status of the e-mail being sent in the background.

:Lingo Sample Code for Director:

Set EmailStatus = EmailDone(Email)

Sample Code for Authorware :

EmailStatus:=CallObject (Email, "EmailDone")

JavaScript Sample Code for Director :

var EmailStatus = Email.EmailDone()

As soon as EmailDone() returns TRUE, call EmailErrorCode() to check whether the email was sent successfully. If EmailErrorCode() returns 0 (zero), the email was sent successfully to all recipients, otherwise the returned value is a number indicating the error that has occurred. You can then call EmailErrorMessage() to get a human-readable string that describes the error.

Step 4 -

  If you want to send another e-mail, jump back to step 2, otherwise delete the DirectEmail instance that you've created in step 1.

Lingo Sample Code for Director : Set Email=0

Sample Code for Authorware : DeleteObject(Email)

JavaScript Sample Code for Director : var Email=0

Sample Code

This chapter includes a sample code for Director and Authorware. Additional, more complex sample Director movies are included with the Xtra.

The sample code in this chapter is based on the implementation steps which were described in the previous section. The sample sends a simple e-mail with the word "Subject" as the e-mail subject and the word "Body" as the e-mail body to the specified recipient, without relaying through a mail server.

Important Notes: For the code to work properly, you'd need to provide New() with your DirectEmail Xtra serial number instead of the number 0. Otherwise, the Xtra will work in an evaluation mode, which is only functional for 14 days.

You'd also need to modify the sender and recipient e-mail addresses appropriately by changing the initialization of the 'Sender' and 'Recipient' variables, respectively. Optionally, to send the e-mail through a relaying mail server, you can initialize the 'MailServer' variable to a relaying mail server address.

Please also note that the following code waits in a repeat loop for emailDone() to return true. We're using a repeat loop here for simplicity reasons. However, Director and Authorware ignore events and halt playback while in a repeat loop. As a result the application may appear to be hung while sending the e-mail and it would take more time for the e-mail to be sent. Therefore it is recommended to wait for emailDone() to return true while processing events and not in an empty repeat loop as we're demonstrating here.

Lingo Sample Code for Director :

Sample Code for Authorware :

JavaScript Sample Code for Director :

 

Sending Faxes

DirectEmail Xtra can also be used to send faxes from Director, Authorware and Shockwave applications.

Faxes can be sent using an e-mail to fax service, a service which turns an e-mail into a fax. There are several key advantages for using such a service:

  • An Internet connection is all that is required for generating and sending faxes. No special hardware is required, such as a phone line or a fax machine.
  • The e-mail to fax service is responsible for handling errors and retrying delivery, such as when the line is busy.
  • The e-mail to fax service is capable of transforming various types of file formats into a fax, including Word, PowerPoint, JPEG, GIF, BMP, Photoshop, TIFF, PNG, PDF and many more, hence eliminating the need for your application to read these files and transform them into a fax.
  • By using DirectEmail Xtra along with an e-mail to fax service you can add faxing capabilities to your applications within minutes.

There are several e-mail to fax services available on the market. This section describes in details how applications can send faxes using DirectEmail Xtra through an e-mail to fax service from eFax. You can try it using the DirectEmail Xtra sample Director movie or by slightly modifying the sample code:

1) Sign up for an eFax plus account. You can send free trial faxes without an eFax account but only to fax numbers in the U.S. If you don't have a fax number in the U.S., eFax can provide you with one free of charge, so you can still test this feature from anywhere in the world and without having an eFax plus account.

2) Set the e-mail sender address to the e-mail account associated with your eFax plus account. If you wish to send free trial faxes, set the sender e-mail address to your e-mail address.

3) Set the e-mail recipient address to fax#@efaxsend.com, where fax# is the recipients full fax telephone number, including country code. For example, to send a fax to (800) 555-1212 in the U.S. (country code 1), the email address would be 18005551212@efaxsend.com.

4) Set the e-mail subject to the cover page subject. If no cover page is desired, or no subject is desired, set the subject to an empty string.

5) Set the text of the message body to the text content of the cover page. If you do not want a cover page, place {nocoverpage} on a line by itself in the message body. Otherwise, a cover page will be generated for your fax.
By default, faxes are sent in Fine mode (200 x 200 dpi). If you want to send your fax in Standard mode (200 x 100 dpi), place {standard} on a line by itself in the message body. In addition, you may optionally specify a 30-character reference number of your own choosing. It should appear on its own line enclosed within curly braces, and preceded by ref#. For example, {ref#123456789}. A reference number can be used to determine the delivery status of one particular fax. If you do not provide your own reference number, one will be created for you.

6) Attach to the e-mail the document to be faxed. A wide variety of file formats is supported, including Word, PowerPoint, JPEG, GIF, BMP, Photoshop, TIFF, PNG, PDF and many more.

For additional information on eFax e-mail to fax service, please visit http://www.efax.com/toolkit/emailinterface.html

Director and Shockwave applications can use DirectEmail Xtra along with our DirectImage Xtra to fax exported images. For example, applications can use DirectImage Xtra to export image cast members or the Director stage or even the whole screen capture into a JPEG file, then fax that file through an e-mail to fax service as explained above.

 

Backward Compatibility Notes 

While DirectEmail Xtra 2 was designed similar to previous versions of the Xtra, it is not fully compatible with them.

Following is a summarize of changes you should make to an existing code using previous versions of the Xtra in order to update it to use the new version.

1) SendEmail() now accepts 'Reply To' address(es) and therefore a 'ReplyTo' parameter was added as the fourth function parameter.

SendEmail() prototype in previous versions of the Xtra was:

SendEmail (object me, string From, string To, string CC, string BCC, string Subject, string Body, string Attachment)

SendEmail() prototype in the current version of the Xtra is:

SendEmail (object me, string From, string To, string ReplyTo, string CC, string BCC, string Subject, string Body, string Attachment)

The new 'Reply To' parameter is optional and will be ignored if an empty string is passed.

2) RegisterDirectEmail() was removed from the Xtra. Your serial number should be passed as the last (and additional) parameter to the New() function.

3) Error codes were extended and as a result changed. If your implementation is checking against a specific error code, you should modify it based on the new error codes.

Congratulations! Your code is now ready to take advantage of the new features in the Xtra.

 

Functions Reference

 

Director: New ( Xtra "DirectEmail", string MailServer, string UserName, string Password, integer SerialNumber )

Authorware: NewObject ("DirectEmail", string MailServer, string UserName, string Password, integer SerialNumber )

Creates a new DirectEmail Xtra instance.

The returned value is a new instance of DirectEmail Xtra.

Parameters :

MailServer : The address of a relaying mail server, or an empty string for sending the e-mails directly to the recipient's e-mail account. For more info, please read the discussion about mail servers.

UserName : User name for logging to the relaying mail server. If no user name is required, or if your application is not relaying on a mail server, pass an empty string as this parameter.

Password : Password for logging to the relaying mail server. If no password is required, or if your application is not relaying on a mail server, pass an empty string as this parameter.

SerialNumber : DirectEmail Xtra Serial Number. If you are using the trial version, pass the number 0.

Returns : DirectEMail instance.

Remarks : This function is Synchronous.

 

Director: Forget ( object me )

Authorware: DeleteObject ( object me )

Deletes a DirectEmail Xtra instance.

Parameter :

object me : DirectEmail Instance.

Returns : None.

Remarks : This function is Synchronous.

In Director, you can also delete the DirectEmail Xtra instance by setting it to zero.

Since this function is synchronous, it might not return immediately if you dispose the instance while a background task is in progress (it calls EmailAbort() internally, in synchronous mode, and times out after 10 seconds).


You can get around the delay by calling EmailAbort() before deleting the instance, to abort the operation in progress properly, as EmailAbort() is asynchronous.

 

SendEmail ( object me, string From, string To, string ReplyTo, string CC, string BCC, string Subject, string Body, string Attachment )

Generates and sends an e-mail.

Parameters :

object me : DirectEmail Instance.

From : The sender's e-mail address.

To : The email address(es) where you want to send the message. 

ReplyTo : The email address where replies to the e-mail should be sent. 

CC : The email address(es) where you want a copy of the message sent. 

BCC : The email address(es) where you want a blind copy of the message
sent. A blind copy does not display the address of the copy
recipient.

Subject : The subject line of the message.

Body : Message body. The message body can be either text or HTML, depends on the mode set by EmailMode(). For text, set this parameter to the message text. For HTML set this parameter to the HTML source. 

Attachment : Exact location of file(s) to attach.

Returns : Error Code.

Remarks : This function is Asynchronous.

Each of the parameters may be an empty string in which case that parameter will be ignored.

Email addresses should be specified in the form of "my@email.com" or
"<my@email.com>" or "My Name (My Title) <my@email.com>"

Multiple addresses and file locations are supported and can be specified separated by commas. For example, to send the e-mail to to@you.com and to@youaswell.com, the 'To' parameter should be "to@you.com,to@youaswell.com".

Safe mode notes:

When the Xtra is in safe mode you can precede each file name in the Attachment parameter with the “|” character in order to attach the specified file from the Shockwave support folder (dswMedia folder). For example, passing “|File.jpg” will have the Xtra attach the file “File.jpg” that is located in the Shockwave support folder.

If no “|” is preceded the file name, and the specified file is located in a local folder named dswMedia, or in one of its sub folders, the Xtra will attach the specified file. Otherwise, a dialog box would appear asking the user to select file(s) to attach.

The safe mode options can be combined. For example, to attach a file named “File.jpg” that is located in the Shockwave support folder and also display a file selection dialog box, set the Attachment parameter to “|File.jpg,select”.

Important Note

After EmailDone() returns true, indicating that the background task has been completed, EmailErrorCode() will return zero (i.e. no error) if the e-mail was sent successfully to all recipients. If the e-mail could not be delivered successfully to one or more recipients, EmailErrorCode() will return 9111. Your application can then call EmailResult() to obtain a list of undeliverable e-mails along with the error code of each failure.

 

VerifyEmail ( object me, string Sender, string EmailAddress )

Verify the specified e-mail address by connecting to the server that hosts the specified e-mail account and checking whether e-mails can be delivered to that account.

If the e-mail is verified without errors, the specified e-mail address is valid and active. Furthermore, a successful verification also means that e-mails can be delivered to the specified recipient without relaying through a mail server.

If an error occurs, and the error is not transient, then the specified e-mail account may be invalid, permanently inactive or temporarily inactive. A permanent error may also indicate that the mail server which hosts the recipient e-mail account refuses to accept inquiries or e-mails from the machine in which the Xtra is running on.

Parameters :

object me : DirectEmail Instance.

Sender : The e-mail address of the sender that intends to send e-mails to the e-mail account to be verified.

EmailAddress : The e-mail address to verify.

Returns : Error Code.

Remarks : This function is Asynchronous.

Multiple addresses are supported and can be specified separated by commas. For example, to check the e-mails to@you.com and to@youaswell.com, the 'EmailAddress' parameter should be "to@you.com,to@youaswell.com".

Email addresses should be specified in the form of "my@email.com" or
"<my@email.com>" or "My Name (My Title) <my@email.com>"

Important Note

After EmailDone() returns true, indicating that the background task has been completed, EmailErrorCode() will return zero (i.e. no error) if all the specified addresses were verified to be deliverable. If one or more emails are undeliverable, EmailErrorCode() will return 9111. Your application can then call EmailResult() to obtain a list of undeliverable e-mails along with the error code of each failure.

Note that some errors are transient, meaning that an e-mail can not currently get delivered to the recipient from the machine running your application due to a temporarily problem such as recipient mail server is down, Internet connection is down, etc, but the e-mail account may still be valid. 

If the returned error code is 10200, 9104, or in the range of 500 to 600, the problem is permanent and the e-mail is undeliverable.

An error in the range of 500 to 600 indicates that the e-mail is undeliverable, though it is still possible that the recipient e-mail account is valid and active. For example, the mail server may return an error because the recipient e-mail account is temporarily full, or because it can only accept e-mails from established mail servers while the Xtra, which takes up on the role of a mail server, is running on a machine with a dynamic IP address.

In order to find out the exact reason for the error, applications should call emailResult() to obtain the SMTP message sent by the server.

 

EmailMode ( object me, integer ModeID )

Sets the mode in which e-mails will be sent. 

Parameters :

object me : DirectEmail Instance.

ModeID : The mode ID. This can be the sum of one or more of the following numbers.

1 Send the e-mail in an HTML mode.
2 Don't mark attachments in-line, so receiving mail clients will not attempt to display them.

For example, set ModeID to 1 in order to set the e-mail body as HTML or to 2 in order to instruct the Xtra not mark attachments in-line. Set ModeID to 3 (1+2) in order to both set the e-mail body to HTML and  instruct the Xtra not mark attachments in-line.

The default is zero, meaning that the e-mail will be sent in plain text with inline attachments.

Returns : Error Code.

Remarks : This function is Synchronous.

 

EmailPort ( object me, integer Port )

Sets the SMTP port. By default the Xtra is using port # 25. 

Parameters :

object me : DirectEmail Instance.

Port : An integer specifying the port number. Can be any number between 1 to  65535.

Returns : Error Code.

Remarks : This function is Synchronous.

 

EmailDone ( object me )

Returns TRUE if the last asynchronous task has been completed and FALSE if not.

Parameter :

object me : DirectEmail Instance.

Returns : TRUE or FALSE.

Remarks : This function is Synchronous.

 

EmailAbort ( object me )

Aborts the current asynchronous task and any associated transfer of data.

Parameter :

object me : DirectEmail Instance.

 

Returns : Error Code.

Remarks : This function is Asynchronous.

 

EmailErrorCode ( object me )

Returns an error code indicating the last error that has occurred.

Parameter :

object me : DirectEmail Instance.

 

Returns : Error Code.

Remarks : This function is Synchronous.

 

EmailErrorMessage ( object me, integer ErrorCode )

Returns a human-readable string that describes the specified error that has occurred. 

If no error string is available for the specified error, an empty string will be returned.

Parameter :

object me : DirectEmail Instance.

ErrorCode : Number of the error to translate into an error message.

 

Returns : Error Message.

Remarks : This function is Synchronous.

All the error codes that are listed at the bottom of this document have an associated human-readable string that describes the error, and which can be obtained using this function. Some other error codes may be returned by the Xtra functions but error strings may not be available for them.

SMTP error messages that are returned by this function are generic, based on the error number. To obtain the exact error message as it was returned by the server, use the EmailResult() function.

 

EmailResult ( object me, integer ResultType )

Returns the text result obtained by the last completed task.

The function should be called after EmailDone() indicates that the task is completed and before the next operation starts.

Parameter :

object me : DirectFTP Instance.

ResultType : Type of text result to retrieve. Pass 1 to retrieve the SMTP messages sent by the server as a result of the last completed task. Pass 2 to retrieve the list of undeliverable recipients as a result of the last completed SendEmail() or VerifyEmail() call. The format of the undeliverable e-mails list is a string containing undeliverable e-mail addresses in the <email@address.com> format,  following by the undeliverable error code. 

For example: "<email@address.com>,XXX,<email2@address.com>,YYY" means that the Xtra could not deliver the e-mail to email@address.com due to error number XXX, and to email2@address.com due to error number YYY. 

Remarks : This function is Synchronous.

 

Error Codes

 

0: Success (no error).

DirectEmail Xtra Errors:

9100: Not enough memory.
9101: A task is already in progress.
9102: No recipient was specified.
9103: Aborted by user.
9104: Invalid email address.
9105: Invalid mail server address.
9106: Invalid user name.
9107: Invalid password.
9108: Mail server is not responding.
9109: Invalid reply from the server.
9111: One or more e-mails were undeliverable.

SMTP Errors:

421: Service not available, closing transmission channel.
450: Mailbox unavailable.
451: Local error in processing.
452: Insufficient system storage.
500: Syntax error, command unrecognized.
501: Syntax error in parameters or arguments.
502: Command not implemented.
503: Bad sequence of commands.
504: Command parameter not implemented.
550: Requested action not taken: mailbox unavailable.
551: User not local.
552: Requested mail action aborted: exceeded storage allocation.
553: Requested action not taken: mailbox name not allowed.
554: Transaction failed.

TCP Errors:

10049: Cannot assign requested address.
10051: Network is unreachable.
10053:
Software caused connection abort.
10054: Connection reset by peer.
10056: Socket is already connected.
10057: Socket is not connected.
10060: Connection timed out.
10061: No connection could be made because the target machine actively refused it.
10065: Host is unreachable.
10091:
Network subsystem is unavailable.
10200: Mail server not found.
10201: Mail server lookup timed out.
10210: Not enough memory.


11001: Host not found.
11004: Valid name, no data record of requested type.

File Errors:

2: The system cannot find the file specified.
3: The system cannot find the path specified.
5: Access is denied.
6: Invalid file handle.
123: The filename, directory name, or volume label syntax is incorrect.

The DirectEmail Xtra functions might return additional platform specific error codes that are not listed above.

 

History

 

2.02.03 - Version 2.1.1 released.

* Added the EmailPort() function.

* When the Xtra is in safe mode it will now display a multiple files selection dialog box under both Windows and MacOS X. In addition, while in safe mode the Xtra will now accept file attachments without the user consent from any local dswMedia folder.

* Minor fixes and improvements.

6.04.02 - Version 2.1 released.

* The Xtra is now fully compatible with MacOS X.

* Additional sample code for both Director and Authorware is now included in the Xtra documentation.

* Revised Xtra documentation with a new section describing how the Xtra can be used to send faxes.

* EmailMode() now accepts another flag to overwrite in-line attachments default.

* Minor fixes and improvements.

 

10.01.01 - Version 2.01 released.

* When the Xtra is in safe mode it can now attach files to the e-mail from the Shockwave support folder (DswMedia folder) without displaying a dialog box.

* Compatibility issue with some mail servers was addressed.

6.07.01 - Version 2.0 released.

6.04.99 - Auto downloadable Shockwave safe package is available.

3.24.99 – Version 1.5.1 released.

11.2.98 – Version 1.5 released. The new version has been redesigned, optimized, improved and is now available for both Windows and MacOS.

6.18.98 – Version 1.0 released.

 



DirectXtras Inc.
P.O Box 2645, Menlo Park, CA, 94026, U.S.A
Voice: +1-415-5058249, Fax: +1-801-8585841
Toll Free: 1-800-4453093
E-mail General Information: info@directxtras.com
E-mail Technical Support: support@directxtras.com

Copyright © 1996-2004 DirectXtras Inc. All Rights Reserved.
WebMaster: tamar@directxtras.com
Last Updated: 9/18/2004 8:36:25 AM.