backIndex

Xelagot action script

Email

As from version 2.99977 the bot may send e-mails. For how to set up the Mailer and send through the User Interface, see Xelagot Topics: Sending Email.

To send e-mail from an action script, you must first prepare the Mailer (that can be done in the script, or the default Mailer values can be used (if they are correctly set up). Next, fill in the e-mail fields, install the event handlers (see Events: EmailSend, EmailSuccess, EmailFailed) and send it with EmailSend, collect the ID code and await the confirmation in the event handlers.

Variables shown in black may be substituted by literal values, variables shown in red are assigned the result of the operation, variables in green may not be substituted by their literal equivalents.

Mailer parameters
EmailHost $a
 REQUIRED FIELD! Sets the SMTP host address. Example:
$a = "smtp.myserver.com"
EmailHost $a
or
EmailHost "smtp.myserver.com"
This is only needed if the program does not know the host, or if you wish to change it for this e-mail sending. To recover the Mailer settings, pass an empty string. See Xelagot Topics: Sending Email. Does not change the program settings for the Mailer.
EmailPort %p
 REQUIRED FIELD! Sets the SMTP port number. Example:
%p = 25
EmailPort %p
or
EmailPort 25
This is only needed if the program does not know the port, which is 25 by default, or if you wish to use another port temporarily. To recover the Mailer settings, pass 0. See Xelagot Topics: Sending Email. Does not change the program settings for the Mailer.
EmailUserID $a
 REQUIRED FIELD? Sets the SMTP logon name. Example:
$a = "xelag"
EmailUserID $a
or
EmailUserID "xelag"
This is only needed if the program does not know the user ID for logon to the SMTP server. Most servers don't require a user ID. To recover the Mailer settings, pass an empty string. See Xelagot Topics: Sending Email. Does not change the program settings for the Mailer.
EmailTimeout %t
 Sets the timeout value in milliseconds for logon. Example, for 30 seconds:
%t = 30000
EmailTimeout %t
or
EmailTimeout 30000
It is not usually necessary to change the default value, which is 10 seconds. To recover the Mailer settings, pass 0. See Xelagot Topics: Sending Email. Does not change the program settings for the Mailer.
EmailFromName $a
 Sets the name of the sender (your name). Example:
$a = "Alex Grigny"
EmailFromName $a
or
EmailFromName "Alex Grigny"
This is not required. To recover the Mailer settings (blank), pass an empty string. See Xelagot Topics: Sending Email. Does not change the program settings for the Mailer.
EmailFromAddress $a
 REQUIRED FIELD! Sets the address of the sender (your e-mail address). Example:
$a = "xelag@3dee.nl"
EmailFromAddress $a
or
EmailFromAddress "xelag@3dee.nl"
This is only needed if the program does not know the sender's address. To recover the Mailer settings, pass an empty string. See Xelagot Topics: Sending Email. Does not change the program settings for the Mailer.
EmailReplyTo $a
 Sets the address where you want the replies to go. Example:
$a = "xelag@3dee.nl"
EmailReplyTo $a
or
EmailReplyTo "xelag@3dee.nl"
Not required. To recover the Mailer settings, pass an empty string. To make sure it is set to the same address as the sender, repeat that address here (otherwise, the Mailer setting wil be used). See Xelagot Topics: Sending Email. Does not change the program settings for the Mailer.
Email parameters
EmailClearParameters
 Clears the following fields: ToAddress, Subject, ToCC, ToBCC, Attachments and Body. These fields are not cleared automatically, they can only be cleared properly using this statement.
EmailToAddress $a
EmailToAddress /s_a
 REQUIRED FIELD! Sets the destination address(es). You mau use a string with comma-separated entries, or a string list with each entry as a separate item. Example:
$a = "xelag@3dee.nl, chris@somewhere.com"
EmailToAddress $a
or
EmailToAddress /s_AddressList
This is absolutely required after a EmailClearParameters statement, unless you wish to use the adresses again after setting them once.
EmailToCC $a
EmailToCC /s_a
 Sets the destination address(es) for Carbon Copies. You may use a string with comma-separated entries, or a string list with each entry as a separate item. Example:
$a = "xelag@3dee.nl, chris@somewhere.com"
EmailToCC $a
or
EmailToCC /s_AddressList
This is absolutely required after a EmailClearParameters statement, unless you wish to use the adresses again after setting them once.
EmailToBCC $a
EmailToBCC /s_a
 Sets the destination address(es) for Blind Carbon Copies. You may use a string with comma-separated entries, or a string list with each entry as a separate item. Example:
$a = "xelag@3dee.nl, chris@somewhere.com"
EmailToCC $a
or
EmailToCC /s_AddressList
This is absolutely required after a EmailClearParameters statement, unless you wish to use the adresses again after setting them once.
EmailAttachments $a
EmailAttachments /s_a
 xelagot 3.606 or older
Sets the path and file names of attachments (full path specification is required at present). You may use a string with comma-separated entries, or a string list with each entry as a separate item. Make sure the full path and filename{s) is specified and that the file(s) exists. Example:
$a = "c:\Program Files\ThisOne.zip"
EmailAttachments $a
or
EmailAttachments /s_AttachmentsList
This is required after a EmailClearParameters statement, unless you wish to use the filenames again after setting them once.

 
EmailAttachments $a [$path]
EmailAttachments /s_a [$path]  
 xelagot 3.607
Sets the path and file names of attachments. You may use a string with comma-separated entries, or a string list with each entry as a separate item. Make sure that the file exists. Optionally, a full path may be specified separately in $path. If the filenames have fully qualified paths (containing drive and path), the $path (if present) is ignored. If the filenames contain relative paths, the path will be relative to the script's folder if $path is omitted, otherwise to $path. The convention used is explained in the section Filenames, with the difference that $path, if present, has precedence over the script's folder.

Confused? Simple examples:
var /s_Attach
...
SListClear /s_Attach
SListAdd /s_Attach "file1.txt"
SListAdd /s_Attach "file2.txt"
EmailAttachments /s_Attach
attaches these two files that are in the script's folder.

var /s_Attach
...
SListClear /s_Attach
SListAdd /s_Attach "attachments\file1.txt"
SListAdd /s_Attach "attachments\file2.txt"
EmailAttachments /s_Attach
attaches these two files that are in the sub-folder 'attachments' in the script's folder.

var /s_Attach, $path
...
SListClear /s_Attach
SListAdd /s_Attach "file1.txt"
SListAdd /s_Attach "file2.txt"
GetMyDir $path
Concat $path $path "attachments\"
EmailAttachments /s_Attach $path
attaches these two files that are in the sub-folder 'attachments' in the script's folder, i.e. does the same as the previous example.

A more complicated example, using symbolic paths. You have your attachment files in User\Attachments (and User is your USBD)
var /s_Attach, $path
...
SListClear /s_Attach
SListAdd /s_Attach "file1.txt"
SListAdd /s_Attach "file2.txt"
$path = "$:usbd\attachments\"
EmailAttachments /s_Attach $path
does the trick.



Another example:
$a = "ThisOne.zip,ThisOther.zip"
GetMyDir $path
EmailAttachments $a $path
or
EmailAttachments /s_AttachmentsList $path

This statement is required after a EmailClearParameters statement, unless you wish to use the filenames again after setting them once.
EmailBody $a
EmailBody /s_a
 Sets the text of the e-mail. You may use a string containing one line of text, or a string list containing the text. Example:
$a = "Hi Susan, see you soon I hope :) XelaG"
EmailBody $a
or
EmailBody /s_MyEmail
This is required after a EmailClearParameters statement, unless you wish to use the same text more than once.
Send Email
EmailSend
EmailSend $ID
 Queues an email in the Mailer (SMTP client) and recovers the emails unique ID code in $ID. This triggers the events EmailSend when the e-mail is picked up from the queue to be sent by the Mailer, EmailSuccess or EmailFailed when the e-mail has been processed by the Mailer.
GetEmailID $a
 OBSOLETE, USE EmailSend $ID
Gets the ID of the Email which is set by the Mailer when executing the SendMail statement. May be recovered inmediately after calling EmailSend.
EmailAbort
 Aborts the current e-mail when sending is being processed, after connection to the SMTP server and before closing the connection.

Example of how to structure these calls. Assumes your mailer knows the Host, Port and Address Sender, and that your code is in the main part of the script:

# at the begining:
var /s_a, $ID, %em
SListSetText /s_a "EmailBody"

# somewhere in your main code:
Label ThisEmail
   OnEmailSendEvent ESend
   OnEmailSuccessEvent ESuccess
   OnEmailFailedEvent EFailed
   EmailClearParameters
   EmailToAddress "xelag@3dee.nl, support@activeworlds.com"
   EmailSubject "testing xelagot"
   EmailBody /s_a
   %em = 0
   EmailSend $ID
Label ThisEmailLoop
   IfInt %em = 0 Goto ThisEmailLoop
# because of this last Goto statement,
# the previous code may not be in an event handler
# your code continues here...

# somewhere in an event handler
# if you wish to send the e-mail from there:
   ResetTo ThisEmail

# Somewhere after the End statement:
 
# text
Text EmailBody
Hi,
I love all bots
but especially my Xelagot :)
Bye
EndText

# event handlers
Event ESend
   GetEventEmailID $a
   IfStringExact $a <> $ID EndEvent
   Concat $b "Sending email " $ID "...."
   Say $b
EndEvent

Event ESuccess
   GetEventEmailID $a
   IfStringExact $a <> $ID EndEvent
   %em = 1
   Concat $b "Email " $ID " sent"
   Say $b
EndEvent

Event EFailed
   GetEventEmailID $a
   GetEventEmailCode $e
   IfStringExact $a <> $ID EndEvent
   %em = 2
   Concat $b "Email " $ID " failed, reason " $e
   Say $b
EndEvent
To see a full working example, look at the event handler for EmailSend.
backIndex