Email class

From PhiWiki
Jump to: navigation, search

The email class enables you to send email from the Phi server to a relay email host including SMTP-Auth if required.

Usage

The email class is a global object in the server scripting environment.

 loadModule('email');
 var e=email;
 e.to='myfriend@domain.com';
 e.from='myaddress@mydomain.com';
 e.subject='hello my friend';
 e.server='smtp.mydomain.com';
 e.data='How are you?';
 var res=e.send();
 if ( res ) { 
   // we have an error with res as SMTP error code
   system.log( e.lasterror );
 };
 loadModule('email');
 var e=email;
 e.from='myaddress@mydomain.com';
 e.subject='hello my friend';
 e.server='smtp.mydomain.com';
 e.user='user@server';
 e.password='mypasswd';
 e.data='<html><body><b>How are you?</b></body></html>';
 e.setHtml( true );
 var res;
 if ( !e.connect() ) { // returns 0 on success
   res=e.sendTo( 'myfriend@domain.com' );
   if ( res ) system.log( e.lasterror ); // res contains SMTP error code
   disconnect();
 }

Note: Email will be sent as plain text (MIME type text/plain) and UTF-8 encoded per default. Since v1.3.0 you can switch to use HTML email bodies using email.setHtml( true ).

Properties

  • String data [read|write]
  • String from [read|write]
  • String lasterror [read]
  • String password [read|write]
  • Number port [read|write]
  • StringArray properties [read]
  • StringArray recipients [read|write]
  • String server [read|write]
  • String subject [read|write]
  • Number timeout [read|write]
  • String to [read|write]
  • String user [read|write]

String data

The message body to be sent. The email will not be sent if data is empty.

email.data='My text in the email body';

String from

From whom the email is sent. The default value is the admin email address of the server.

email.from='info@phisys.com';

String lasterror

Returns the last error occured.

var err=email.lasterror;

String password

Sets the password for user authentication in plain text (internally it will be Base64 encoded) for the SMTP server.

email.password='mypass_on_email_server';

Warning: Passwords are transmitted base64 encoded (i.e. they are not encrypted nor secure!)

See also: email.user, Additional notes.

Number port

Sets the port the email server is listening on. Default is '25'.

email.port=587;

StringArray properties

Returns the available properties for the email class in a string array.

var i=0;
while ( email.properties[i] ) print( email.properties[i++] );

StringArray recipients

A list of recipients to which the email should be sent.

var list=new Array();
list[0]='mail1@domain.com';
list[1]='mail2@otherdomain.com';
email.recipients=list;

String server

Contains the SMTP server address (default is localhost).

email.server='smtp.domain.com';

String subject

Sets the subject of the email.

email.subject='the world is great!';

Number timeout

Sets the timeout in ms if an email server is not answering. Default is '20000' (20 sec).

email.timeout=10000; // timeout after 10 seconds

String to

Recipient of the email (if only one). Use email.recipients if you need multiple recipients.

email.to='info@domain.com';

Note: This will set also the 'To:' header, so if you provide at least one email recipient in email.recipients you can use this for example to overwrite the valid email address:

email.addRecipient( 'user1@domain1.com' );
email.addRecipient( 'user2@domain2.com' );
email.to='undisclosed recipients'

String user

The user name for SMTP authentication.

email.user='login_name';

See also: email.password.

Functions

Void addRecipient()

Adds a email recipient to the list of recipients.

email.addRecipient( 'user@domain.com' );
email.addRecipient( 'user2@domain2.com' );

See also: email.recipients.

Number connect()

v1.3.0 Establishes a connection to the SMTP server using server, port, user and password information of the email object. If you open a connection you also need to close it with email.disconnect() after sending you emails. You can use email.send() as a short hand. Returns '0' on success or the appropriate error code.

email.server='smtp.mydomain.com';
email.port=587; // overwrites 25
var res=email.connect();
if ( res ) { doSomething(); } // an error occured

See also: email.sendTo(), email.disconnect().

Number disconnect()

v1.3.0 Disconnects from an SMTP server. Returns '0' on success.

See also: email.connect().

Boolean html()

v1.3.0 Returns if the email object operates in HTML mode, i.e. the email body uses HTML tags.

var ishtml=email.html();

See also: email.setHtml().

Number send()

Sends the email. Returns '0' on success or the error code of the email dialog. This is a short hand for connect() - sendTo() - disconnect(). Uses email.subject and email.data as content. If you have multiple recipients with the same subject and email body you can set email.recipients otherwise email.to is used.

var res=email.send();
if ( res ) {
  // an error occured
  system.log( email.lasterror );
}

See also: email.lasterror.

Number sendTo()

v1.3.0 Sends an email to recipient. A connection must already be established via email.connect(). Uses the email.from property as the FROM envelope and From: header. If body or subject is omitted, the data from email.data or email.subject is used. This allows multiple emails to be sent (even with different mail bodies) without disconnecting.

Returns '0' on success, or the SMTP error code.

var res=email.sendTo( recipient, subject=String(), body=String() );
var addresses=['myfriend@domain1.com', 'partner@domain2.com'];
var res=email.connect();
if ( res ) system.log( email.lasterror );
else {
  var i=0;
  while ( email.addresses[i] ) { 
    res=sendTo( addresses[i++], 'Hello my friend', 'This is a fancy email body' );
    if ( res ) system.log( email.lasterror );
  }
  email.disconnect();
}

Void setHtml()

v1.3.0 Sets the body content type to text/html if mode is true or back to text/plain if mode is false.

email.setHtml( mode );

See also: email.html().

Additional notes

Email over secure connections (SMTPS or STARTTLS) are currently not supported.