ipworks
Class Htmlmailer

java.lang.Object
  |
  +--ipworks.Htmlmailer

public class Htmlmailer

extends java.lang.Object

The HTMLMailer bean is used to send HTML email.

The bean sends a message (provided in MessageHTML and MessageText ). The HTML message may contain references to images which are automatically embedded into the message.

The MessageHTML property contains the HTML version of the message. The corresponding plain text version is provided into the MessageText property.

When MessageHTML is set, the bean automatically computes a plaintext version of the text and puts it into MessageText . You may choose to override this default text with your own version.

The recipients are specified by the SendTo , Cc , and BCc properties, and the message subject by the Subject property.

Once all the appropriate properties have been set call the Send method and your message will be sent to its intended recipient(s).

Other SMTP headers may be specified through the OtherHeaders property. Information about interaction with the server is provided via the PITrail event.

Field Summary

static int	amCRAMMD5
static int	amNTLM
static int	amUserPassword
static int	epNonUrgent
static int	epNormal
static int	epUnspecified
static int	epUrgent
static int	esCompanyConfidential
static int	esPersonal
static int	esPrivate
static int	esUnspecified
static int	miHigh
static int	miLow
static int	miNormal
static int	miUnspecified

Constructor Summary

Htmlmailer()

Method Summary

void	addAttachment(java.lang.String fileName) Adds FileName as an attachment.
void	addHtmlmailerEventListener(ipworks.HtmlmailerEventListener l)
java.lang.String	config(java.lang.String configurationString) Sets or retrieves a beanconfiguration setting.
void	connect() Connects to the mail relay and sends the SMTP HELO command.
void	disconnect() Disconnect from the SMTP server.
void	doEvents() Processes events from the internal message queue.
FileAttachmentList	getAttachments() The paths of files to attach to the message.
int	getAuthMechanism() The authentication mechanism to be used when connecting to the mail server.
java.lang.String	getBCc() A comma separated list of addresses for blind carbon copies (optional).
java.lang.String	getCc() A comma separated list of addresses for carbon copies (optional).
java.lang.String	getDeliveryNotificationTo() Email address to send a delivery notification to.
ipworks.Firewall	getFirewall() A set of properties related to firewall access.
java.lang.String	getFrom() The email address of the sender (required).
java.lang.String	getHTMLFile() The path to a local HTML file.
HTMLImageList	getImages() The embedded images in the HTML message.
int	getImportance() Importance of the mail message (optional).
java.lang.String	getLastReply() The last reply from the server.
java.lang.String	getLocalHost() The name of the local host or user-assigned IP interface through which connections are initiated or accepted.
int	getMailPort() The server port for SMTP (default 25).
java.lang.String	getMailServer() The name or address of a mail server (mail relay).
java.lang.String	getMessageDate() The Date of the mail message (optional).
java.lang.String	getMessageHTML() The HTML version of the message.
java.lang.String	getMessageId() The MessageId for the message.
MessageRecipientList	getMessageRecipients() The collection of recipients of the message.
java.lang.String	getMessageText() The plain text version of the message.
java.lang.String	getOtherHeaders() An RFC 822 compliant string consisting of extra headers.
java.lang.String	getPassword() A login password to login with in the MailServer .
int	getPriority() Priority of the mail message (optional).
java.lang.String	getReadReceiptTo() Email address to send a read receipt to.
java.lang.String	getReplyTo() A mail address to reply to (optional).
java.lang.String	getSendTo() A comma separated list of addresses for destinations (required).
int	getSensitivity() Sensitivity of the mail message (optional).
java.lang.String	getSubject() The subject of the mail message (optional).
int	getTimeout() A timeout for the bean.
java.lang.String	getUser() A user id to login as in the MailServer .
void	interrupt() Interrupt the current method.
boolean	isConnected() Shows whether the bean is connected.
boolean	isIdle() The current status of the component.
boolean	isParseHTML() Controls the behavior of the MessageHTML property.
void	processQueue(java.lang.String queueDir) Sends the messages which have previously been queued into QueueDir .
java.lang.String	queue(java.lang.String queueDir) Queues the message into QueueDir .
void	removeHtmlmailerEventListener(ipworks.HtmlmailerEventListener l)
void	resetHeaders() Resets all the message headers to empty.
void	send() Send the current message and MIME encoded attachment.
void	setAttachments(FileAttachmentList attachments) The paths of files to attach to the message.
void	setAuthMechanism(int authMechanism) The authentication mechanism to be used when connecting to the mail server.
void	setBCc(java.lang.String BCc) A comma separated list of addresses for blind carbon copies (optional).
void	setCc(java.lang.String cc) A comma separated list of addresses for carbon copies (optional).
void	setCommand(java.lang.String command) Can be used to send additional commands directly to the server.
void	setConnected(boolean connected) Shows whether the bean is connected.
void	setDeliveryNotificationTo(java.lang.String deliveryNotificationTo) Email address to send a delivery notification to.
void	setFirewall(ipworks.Firewall firewall) A set of properties related to firewall access.
void	setFrom(java.lang.String from) The email address of the sender (required).
void	setHTMLFile(java.lang.String HTMLFile) The path to a local HTML file.
void	setImages(HTMLImageList images) The embedded images in the HTML message.
void	setImportance(int importance) Importance of the mail message (optional).
void	setLocalHost(java.lang.String localHost) The name of the local host or user-assigned IP interface through which connections are initiated or accepted.
void	setMailPort(int mailPort) The server port for SMTP (default 25).
void	setMailServer(java.lang.String mailServer) The name or address of a mail server (mail relay).
void	setMessageDate(java.lang.String messageDate) The Date of the mail message (optional).
void	setMessageHTML(java.lang.String messageHTML) The HTML version of the message.
void	setMessageHTMLStream(java.io.InputStream messageStream) Send the current message and MIME encoded attachment.
void	setMessageId(java.lang.String messageId) The MessageId for the message.
void	setMessageRecipients(MessageRecipientList messageRecipients) The collection of recipients of the message.
void	setMessageText(java.lang.String messageText) The plain text version of the message.
void	setOtherHeaders(java.lang.String otherHeaders) An RFC 822 compliant string consisting of extra headers.
void	setParseHTML(boolean parseHTML) Controls the behavior of the MessageHTML property.
void	setPassword(java.lang.String password) A login password to login with in the MailServer .
void	setPriority(int priority) Priority of the mail message (optional).
void	setReadReceiptTo(java.lang.String readReceiptTo) Email address to send a read receipt to.
void	setReplyTo(java.lang.String replyTo) A mail address to reply to (optional).
void	setSendTo(java.lang.String sendTo) A comma separated list of addresses for destinations (required).
void	setSensitivity(int sensitivity) Sensitivity of the mail message (optional).
void	setSubject(java.lang.String subject) The subject of the mail message (optional).
void	setTimeout(int timeout) A timeout for the bean.
void	setUser(java.lang.String user) A user id to login as in the MailServer .

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

amUserPassword

public static final int amUserPassword

See Also:

Constant Field Values

amCRAMMD5

public static final int amCRAMMD5

See Also:

Constant Field Values

amNTLM

public static final int amNTLM

See Also:

Constant Field Values

miUnspecified

public static final int miUnspecified

See Also:

Constant Field Values

miHigh

public static final int miHigh

See Also:

Constant Field Values

miNormal

public static final int miNormal

See Also:

Constant Field Values

miLow

public static final int miLow

See Also:

Constant Field Values

epUnspecified

public static final int epUnspecified

See Also:

Constant Field Values

epNormal

public static final int epNormal

See Also:

Constant Field Values

epUrgent

public static final int epUrgent

See Also:

Constant Field Values

epNonUrgent

public static final int epNonUrgent

See Also:

Constant Field Values

esUnspecified

public static final int esUnspecified

See Also:

Constant Field Values

esPersonal

public static final int esPersonal

See Also:

Constant Field Values

esPrivate

public static final int esPrivate

See Also:

Constant Field Values

esCompanyConfidential

public static final int esCompanyConfidential

See Also:

Constant Field Values

Constructor Detail

Htmlmailer

public Htmlmailer()

Method Detail

getAttachments

public FileAttachmentList getAttachments()

The paths of files to attach to the message.

Set this property to the path of a file on your system that you would like to send as an attachment with your message. The bean will open the file and encode its contents in MIME format.

Example (Adding an Attachment)

 Control.AddAttachment("C:\\file1.zip")
 Control.AddAttachment("C:\\file2.zip")
 Control.Send() 

This collection is indexed from 0 to Count - 1.

setAttachments

public void setAttachments(FileAttachmentList attachments)
                    throws IPWorksException

The paths of files to attach to the message.

Set this property to the path of a file on your system that you would like to send as an attachment with your message. The bean will open the file and encode its contents in MIME format.

Example (Adding an Attachment)

 Control.AddAttachment("C:\\file1.zip")
 Control.AddAttachment("C:\\file2.zip")
 Control.Send() 

This collection is indexed from 0 to Count - 1.

IPWorksException

getAuthMechanism

public int getAuthMechanism()

The authentication mechanism to be used when connecting to the mail server.

By default, AuthMechanism is amUserPassword (0), and if the User and Password properties are set, the AUTH command is sent to the server for authentication. If AuthMechanism is set to amCRAMMD5 (1), CRAM-MD5 authentication is used instead.

If AuthMechanism is set to amNTLM (2) NTLM authentication will be used. This option is only available in the SSL package.

setAuthMechanism

public void setAuthMechanism(int authMechanism)
                      throws IPWorksException

The authentication mechanism to be used when connecting to the mail server.

By default, AuthMechanism is amUserPassword (0), and if the User and Password properties are set, the AUTH command is sent to the server for authentication. If AuthMechanism is set to amCRAMMD5 (1), CRAM-MD5 authentication is used instead.

If AuthMechanism is set to amNTLM (2) NTLM authentication will be used. This option is only available in the SSL package.

IPWorksException

getBCc

public java.lang.String getBCc()

A comma separated list of addresses for blind carbon copies (optional).

The BCc property specifies a comma separated list of destinations for blind carbon copies of the mail message. A copy of the message is sent to each destination, but no BCc SMTP header is created containing the destination addresses, so individual recipients never see the list of the other recipients.

The bean will return an error if the MailServer returns an error code about any email address specified in SendTo or Cc but it will only fire an Error event if the same happens with an email address specified in BCc .

If the resulting header is longer thanMaxHeaderLength, then it is folded according to RFC 822 specifications.

NOTE: You must clear the MessageRecipients collection before setting this property to remove previous recipients.

setBCc

public void setBCc(java.lang.String BCc)
            throws IPWorksException

A comma separated list of addresses for blind carbon copies (optional).

The BCc property specifies a comma separated list of destinations for blind carbon copies of the mail message. A copy of the message is sent to each destination, but no BCc SMTP header is created containing the destination addresses, so individual recipients never see the list of the other recipients.

The bean will return an error if the MailServer returns an error code about any email address specified in SendTo or Cc but it will only fire an Error event if the same happens with an email address specified in BCc .

If the resulting header is longer thanMaxHeaderLength, then it is folded according to RFC 822 specifications.

NOTE: You must clear the MessageRecipients collection before setting this property to remove previous recipients.

IPWorksException

getCc

public java.lang.String getCc()

A comma separated list of addresses for carbon copies (optional).

The Cc property specifies a comma separated list of destinations for carbon copies of the mail message. A copy of the message is sent to each destination, and a Cc SMTP header is created containing the destination addresses. This header is sent to every recipient of the message. If you don't want to copy this information to every recipient, then use blind carbon copies instead (see the description of the BCc ).

The bean will return an error if the MailServer returns an error code about any email address specified in SendTo or Cc but it will only fire an Error event if the same happens with an email address specified in BCc .

If the resulting header is longer thanMaxHeaderLength, then it is folded according to RFC 822 specifications.

NOTE: You must clear the MessageRecipients collection before setting this property to remove previous recipients.

setCc

public void setCc(java.lang.String cc)
           throws IPWorksException

A comma separated list of addresses for carbon copies (optional).

The Cc property specifies a comma separated list of destinations for carbon copies of the mail message. A copy of the message is sent to each destination, and a Cc SMTP header is created containing the destination addresses. This header is sent to every recipient of the message. If you don't want to copy this information to every recipient, then use blind carbon copies instead (see the description of the BCc ).

The bean will return an error if the MailServer returns an error code about any email address specified in SendTo or Cc but it will only fire an Error event if the same happens with an email address specified in BCc .

If the resulting header is longer thanMaxHeaderLength, then it is folded according to RFC 822 specifications.

NOTE: You must clear the MessageRecipients collection before setting this property to remove previous recipients.

IPWorksException

setCommand

public void setCommand(java.lang.String command)
                throws IPWorksException

Can be used to send additional commands directly to the server.

Check the LastReply property and/or trap the PITrail events comming from the server to get the response.

IPWorksException

isConnected

public boolean isConnected()

Shows whether the bean is connected.

Use this property to determine whether the bean is connected to the remote host or not.

setConnected

public void setConnected(boolean connected)
                  throws IPWorksException

Shows whether the bean is connected.

Use this property to determine whether the bean is connected to the remote host or not.

IPWorksException

getDeliveryNotificationTo

public java.lang.String getDeliveryNotificationTo()

Email address to send a delivery notification to.

When set, a Return-Receipt-To header is added to the message. DeliveryNotificationTo should be set to an email address which should receive the delivery notification.

setDeliveryNotificationTo

public void setDeliveryNotificationTo(java.lang.String deliveryNotificationTo)
                               throws IPWorksException

Email address to send a delivery notification to.

When set, a Return-Receipt-To header is added to the message. DeliveryNotificationTo should be set to an email address which should receive the delivery notification.

IPWorksException

getFirewall

public ipworks.Firewall getFirewall()

A set of properties related to firewall access.

This is a FIREWALL type property which contains fields describing the firewall through which the bean will attempt to connect. ;

setFirewall

public void setFirewall(ipworks.Firewall firewall)
                 throws IPWorksException

A set of properties related to firewall access.

This is a FIREWALL type property which contains fields describing the firewall through which the bean will attempt to connect. ;

IPWorksException

getFrom

public java.lang.String getFrom()

The email address of the sender (required).

The From property is used to create a From SMTP header. This header identifies the sender of the message. A valid email address is required. Examples of valid addresses are: "Friendly Name" <address@company.com> or address@company.com

If the resulting header is longer thanMaxHeaderLength, then it is folded according to RFC 822 specifications.

setFrom

public void setFrom(java.lang.String from)
             throws IPWorksException

The email address of the sender (required).

The From property is used to create a From SMTP header. This header identifies the sender of the message. A valid email address is required. Examples of valid addresses are: "Friendly Name" <address@company.com> or address@company.com

If the resulting header is longer thanMaxHeaderLength, then it is folded according to RFC 822 specifications.

IPWorksException

getHTMLFile

public java.lang.String getHTMLFile()

The path to a local HTML file.

If HTMLFile is not empty, the contents of the file with that name will be appended to the text in MessageHTML .

Note that this means that if MessageHTML is empty, HTMLFile is what will be sent to the server.

As a side effect, the current directory is set to the directory where MessageHTML is located.

setHTMLFile

public void setHTMLFile(java.lang.String HTMLFile)
                 throws IPWorksException

The path to a local HTML file.

If HTMLFile is not empty, the contents of the file with that name will be appended to the text in MessageHTML .

Note that this means that if MessageHTML is empty, HTMLFile is what will be sent to the server.

As a side effect, the current directory is set to the directory where MessageHTML is located.

IPWorksException

isIdle

public boolean isIdle()

The current status of the component.

Idle will be False if the component is currently busy (communicating and/or waiting for an answer), and True at all other times.

getImages

public HTMLImageList getImages()

The embedded images in the HTML message.

The Images collection contains the names of the image files embedded into the HTML message. The collection is updated every time MessageHTML is set. You may change the file names prior to sending (e.g. if they don't point to valid files).

This collection is indexed from 0 to Count - 1.

setImages

public void setImages(HTMLImageList images)
               throws IPWorksException

The embedded images in the HTML message.

The Images collection contains the names of the image files embedded into the HTML message. The collection is updated every time MessageHTML is set. You may change the file names prior to sending (e.g. if they don't point to valid files).

This collection is indexed from 0 to Count - 1.

IPWorksException

getImportance

public int getImportance()

Importance of the mail message (optional).

When set, an Importance header will added to the message.

Importance is an indication to the recipient(s) about how important the message is. The possible values are High (1), Normal (2), and Low (3).

setImportance

public void setImportance(int importance)
                   throws IPWorksException

Importance of the mail message (optional).

When set, an Importance header will added to the message.

Importance is an indication to the recipient(s) about how important the message is. The possible values are High (1), Normal (2), and Low (3).

IPWorksException

getLastReply

public java.lang.String getLastReply()

The last reply from the server.

This is the last reply received from the server. It can be used for information purposes. The same information and more can also be retrieved through the PITrail event.

getLocalHost

public java.lang.String getLocalHost()

The name of the local host or user-assigned IP interface through which connections are initiated or accepted.

The LocalHost property contains the name of the local host as obtained by the gethostname() system call, or if the user has assigned an IP address, the value of that address.

In multihomed hosts (machines with more than one IP interface) setting LocalHost to the value of an interface will make the bean initiate connections (or accept in the case of server beans) only through that interface.

If the bean is connected, the LocalHost property shows the IP address of the interface through which the connection is made in internet dotted format (aaa.bbb.ccc.ddd). In most cases, this is the address of the local host, except for multihomed hosts (machines with more than one IP interface).

NOTE: LocalHost is not persistent. You must always set it in code, and never in the property window.

setLocalHost

public void setLocalHost(java.lang.String localHost)
                  throws IPWorksException

The name of the local host or user-assigned IP interface through which connections are initiated or accepted.

The LocalHost property contains the name of the local host as obtained by the gethostname() system call, or if the user has assigned an IP address, the value of that address.

In multihomed hosts (machines with more than one IP interface) setting LocalHost to the value of an interface will make the bean initiate connections (or accept in the case of server beans) only through that interface.

If the bean is connected, the LocalHost property shows the IP address of the interface through which the connection is made in internet dotted format (aaa.bbb.ccc.ddd). In most cases, this is the address of the local host, except for multihomed hosts (machines with more than one IP interface).

NOTE: LocalHost is not persistent. You must always set it in code, and never in the property window.

IPWorksException

getMailPort

public int getMailPort()

The server port for SMTP (default 25).

A valid port number (a value between 1 and 65535) is required for the connection to take place. The property must be set before a connection is attempted and cannot be changed once a connection is established. Any attempt to change this property while connected will fail with an error.

setMailPort

public void setMailPort(int mailPort)
                 throws IPWorksException

The server port for SMTP (default 25).

A valid port number (a value between 1 and 65535) is required for the connection to take place. The property must be set before a connection is attempted and cannot be changed once a connection is established. Any attempt to change this property while connected will fail with an error.

IPWorksException

getMailServer

public java.lang.String getMailServer()

The name or address of a mail server (mail relay).

The MailServer property specifies the IP address (IP number in dotted internet format) or Domain Name for a mail relay through which messages will be routed. It is set before a connection is attempted and cannot be changed once a connection is in progress.

The current version of the bean does not provide a default value for the mail relay. You must provide a host name yourself. Generally, any internet host with an SMTP server will suffice (a UNIX host for example), but it is preferable to select a MailServer that is close to the machine sending mail.

If the MailServer property is set to a Domain Name, a DNS request is initiated and upon successful termination of the request, the MailServer property is set to the corresponding address. If the search is not successful, an error is returned.

If the bean is configured to use a SOCKS firewall, the value assigned to this property may be preceeded with a "*". If this is the case, the host name is passed to the firewall unresolved and the firewall performs the DNS resolution.

setMailServer

public void setMailServer(java.lang.String mailServer)
                   throws IPWorksException

The name or address of a mail server (mail relay).

The MailServer property specifies the IP address (IP number in dotted internet format) or Domain Name for a mail relay through which messages will be routed. It is set before a connection is attempted and cannot be changed once a connection is in progress.

The current version of the bean does not provide a default value for the mail relay. You must provide a host name yourself. Generally, any internet host with an SMTP server will suffice (a UNIX host for example), but it is preferable to select a MailServer that is close to the machine sending mail.

If the MailServer property is set to a Domain Name, a DNS request is initiated and upon successful termination of the request, the MailServer property is set to the corresponding address. If the search is not successful, an error is returned.

If the bean is configured to use a SOCKS firewall, the value assigned to this property may be preceeded with a "*". If this is the case, the host name is passed to the firewall unresolved and the firewall performs the DNS resolution.

IPWorksException

getMessageDate

public java.lang.String getMessageDate()

The Date of the mail message (optional).

If the MessageDate property contains a non-empty string, then a Date SMTP header is created and attached to the message. If not, then the date information is added by the mail relay(s) the message goes through.

Special case: if MessageDate is set to the special value "*", a Date SMTP header reflecting the current date and time is generated when MessageHeaders is computed and the message is sent.

RFC 822 contains detailed date format specifications. An example of a valid date is "Fri, 1 Mar 96 21:24:52 EST".

setMessageDate

public void setMessageDate(java.lang.String messageDate)
                    throws IPWorksException

The Date of the mail message (optional).

If the MessageDate property contains a non-empty string, then a Date SMTP header is created and attached to the message. If not, then the date information is added by the mail relay(s) the message goes through.

Special case: if MessageDate is set to the special value "*", a Date SMTP header reflecting the current date and time is generated when MessageHeaders is computed and the message is sent.

RFC 822 contains detailed date format specifications. An example of a valid date is "Fri, 1 Mar 96 21:24:52 EST".

IPWorksException

getMessageHTML

public java.lang.String getMessageHTML()

The HTML version of the message.

The MessageHTML property contains the HTML version of the message. The corresponding plain text version is provided into the MessageText property.

When MessageHTML is set, the bean automatically computes a plaintext version of the text and puts it into MessageText . You may choose to override this default text with your own version.

Example (Setting MessageHTML)

 HTMLMailerControl.MessageHTML = "<b>Hello</b>, my name is <i>Tom</i>" 

setMessageHTML

public void setMessageHTML(java.lang.String messageHTML)
                    throws IPWorksException

The HTML version of the message.

The MessageHTML property contains the HTML version of the message. The corresponding plain text version is provided into the MessageText property.

When MessageHTML is set, the bean automatically computes a plaintext version of the text and puts it into MessageText . You may choose to override this default text with your own version.

Example (Setting MessageHTML)

 HTMLMailerControl.MessageHTML = "<b>Hello</b>, my name is <i>Tom</i>" 

IPWorksException

getMessageId

public java.lang.String getMessageId()

The MessageId for the message.

When set, the value of MessageId is used as the Message-ID header value of the message. A special value of "*" will automatically generate a random unique id for the message.

setMessageId

public void setMessageId(java.lang.String messageId)
                  throws IPWorksException

The MessageId for the message.

When set, the value of MessageId is used as the Message-ID header value of the message. A special value of "*" will automatically generate a random unique id for the message.

IPWorksException

getMessageRecipients

public MessageRecipientList getMessageRecipients()

The collection of recipients of the message.

This collection describes whom the message is being sent to. You may include all recipients in this property, even Cc's and BCc's, which are specified by the type field.

This collection is indexed from 0 to Count - 1.

setMessageRecipients

public void setMessageRecipients(MessageRecipientList messageRecipients)
                          throws IPWorksException

The collection of recipients of the message.

This collection describes whom the message is being sent to. You may include all recipients in this property, even Cc's and BCc's, which are specified by the type field.

This collection is indexed from 0 to Count - 1.

IPWorksException

getMessageText

public java.lang.String getMessageText()

The plain text version of the message.

MessageText is a plain text version of the HTML message. This is neccessary for recipients with legacy mail readers that do not support HTML.

The MessageHTML property contains the HTML version of the message. When MessageHTML is set, the bean automatically computes a plaintext version of the text and puts it into MessageText . You may choose to override this default text with your own version.

setMessageText

public void setMessageText(java.lang.String messageText)
                    throws IPWorksException

The plain text version of the message.

MessageText is a plain text version of the HTML message. This is neccessary for recipients with legacy mail readers that do not support HTML.

The MessageHTML property contains the HTML version of the message. When MessageHTML is set, the bean automatically computes a plaintext version of the text and puts it into MessageText . You may choose to override this default text with your own version.

IPWorksException

getOtherHeaders

public java.lang.String getOtherHeaders()

An RFC 822 compliant string consisting of extra headers.

The OtherHeaders property contains a string of headers to be appended to the message headers created from other properties like SendTo , Subject , etc.

The headers must of the format "header: value" as specified in RFC 822. Header lines should be separated by CRLF ("\\r\\n") .

Use this property with caution. If OtherHeaders contains invalid headers, message delivery might not be successful.

The OtherHeaders property is useful for extending the functionality of the bean. A good example is delivery of MIME encoded messages.

SPECIAL CASE: if OtherHeaders starts with an empty line (CRLF), then the value of OtherHeaders is used instead of the normally computed message headers.

Example (Send an Email With Additional Header)

 control.MailServer = "MyServer"
 control.From = "me@server.com"
 control.SendTo = "recipient@server.com"
 control.Subject = "My Subject"
 control.MessageText = "This is the message body"
 control.OtherHeaders = "HeaderName: Headervalue"
 control.Send() 

setOtherHeaders

public void setOtherHeaders(java.lang.String otherHeaders)
                     throws IPWorksException

An RFC 822 compliant string consisting of extra headers.

The OtherHeaders property contains a string of headers to be appended to the message headers created from other properties like SendTo , Subject , etc.

The headers must of the format "header: value" as specified in RFC 822. Header lines should be separated by CRLF ("\\r\\n") .

Use this property with caution. If OtherHeaders contains invalid headers, message delivery might not be successful.

The OtherHeaders property is useful for extending the functionality of the bean. A good example is delivery of MIME encoded messages.

SPECIAL CASE: if OtherHeaders starts with an empty line (CRLF), then the value of OtherHeaders is used instead of the normally computed message headers.

Example (Send an Email With Additional Header)

 control.MailServer = "MyServer"
 control.From = "me@server.com"
 control.SendTo = "recipient@server.com"
 control.Subject = "My Subject"
 control.MessageText = "This is the message body"
 control.OtherHeaders = "HeaderName: Headervalue"
 control.Send() 

IPWorksException

isParseHTML

public boolean isParseHTML()

Controls the behavior of the MessageHTML property.

If ParseHTML is set to False, you must provide valid values in MessageHTML , MessageText , and Images .

setParseHTML

public void setParseHTML(boolean parseHTML)
                  throws IPWorksException

Controls the behavior of the MessageHTML property.

If ParseHTML is set to False, you must provide valid values in MessageHTML , MessageText , and Images .

IPWorksException

getPassword

public java.lang.String getPassword()

A login password to login with in the MailServer .

If the Password property is set to a non-empty string, then when connecting to the MailServer an AUTH or CRAM-MD5 (depending on the value of AuthMechanism ) command is sent in order to provide authentication information for the user.

setPassword

public void setPassword(java.lang.String password)
                 throws IPWorksException

A login password to login with in the MailServer .

If the Password property is set to a non-empty string, then when connecting to the MailServer an AUTH or CRAM-MD5 (depending on the value of AuthMechanism ) command is sent in order to provide authentication information for the user.

IPWorksException

getPriority

public int getPriority()

Priority of the mail message (optional).

When set, a Priority header will be added to the message. Priority is an indication about the delivery priority of the message. The possible values are epNormal, epUrgent, and epNonUrgent.

setPriority

public void setPriority(int priority)
                 throws IPWorksException

Priority of the mail message (optional).

When set, a Priority header will be added to the message. Priority is an indication about the delivery priority of the message. The possible values are epNormal, epUrgent, and epNonUrgent.

IPWorksException

getReadReceiptTo

public java.lang.String getReadReceiptTo()

Email address to send a read receipt to.

When set, a Disposition-Notification-To header is added to the message. ReadReceiptTo should be set to an email address which should receive the read-receipt.

setReadReceiptTo

public void setReadReceiptTo(java.lang.String readReceiptTo)
                      throws IPWorksException

Email address to send a read receipt to.

When set, a Disposition-Notification-To header is added to the message. ReadReceiptTo should be set to an email address which should receive the read-receipt.

IPWorksException

getReplyTo

public java.lang.String getReplyTo()

A mail address to reply to (optional).

If the ReplyTo property contains a non-empty string, a Reply-To SMTP header is created for the message. This header shows the address to use for replies (useful if this address is different from the one in From ).

If the resulting header is longer thanMaxHeaderLength, then it is folded according to RFC 822 specifications.

setReplyTo

public void setReplyTo(java.lang.String replyTo)
                throws IPWorksException

A mail address to reply to (optional).

If the ReplyTo property contains a non-empty string, a Reply-To SMTP header is created for the message. This header shows the address to use for replies (useful if this address is different from the one in From ).

If the resulting header is longer thanMaxHeaderLength, then it is folded according to RFC 822 specifications.

IPWorksException

getSendTo

public java.lang.String getSendTo()

A comma separated list of addresses for destinations (required).

The SendTo property specifies a comma separated list of destinations for the mail message. A copy of the message is sent to each of them, and a To SMTP header is created containing the destination addresses.

Examples of valid addresses are: "Friendly Name" <address@company.com> or address@company.com

The bean will fail if the MailServer returns an error code about any email address specified in SendTo or Cc but it will silently ignore the error if the same happens with an email address specified in BCc .

If the resulting header is longer thanMaxHeaderLength, then it is folded according to RFC 822 specifications.

NOTE: You must clear the MessageRecipients collection before setting this property to remove previous recipients.

setSendTo

public void setSendTo(java.lang.String sendTo)
               throws IPWorksException

A comma separated list of addresses for destinations (required).

The SendTo property specifies a comma separated list of destinations for the mail message. A copy of the message is sent to each of them, and a To SMTP header is created containing the destination addresses.

Examples of valid addresses are: "Friendly Name" <address@company.com> or address@company.com

The bean will fail if the MailServer returns an error code about any email address specified in SendTo or Cc but it will silently ignore the error if the same happens with an email address specified in BCc .

If the resulting header is longer thanMaxHeaderLength, then it is folded according to RFC 822 specifications.

NOTE: You must clear the MessageRecipients collection before setting this property to remove previous recipients.

IPWorksException

getSensitivity

public int getSensitivity()

Sensitivity of the mail message (optional).

An indication of how sensitive it is to disclose the message to people other than the recipients of the message. When set, a Sensitivity header will added to the message. Possible values are: esPersonal (1), esPrivate (2), and esCompanyConfidential (3).

setSensitivity

public void setSensitivity(int sensitivity)
                    throws IPWorksException

Sensitivity of the mail message (optional).

An indication of how sensitive it is to disclose the message to people other than the recipients of the message. When set, a Sensitivity header will added to the message. Possible values are: esPersonal (1), esPrivate (2), and esCompanyConfidential (3).

IPWorksException

getSubject

public java.lang.String getSubject()

The subject of the mail message (optional).

The string in Subject is sent with a Subject SMTP header to the mail recipient.

If the resulting header is longer thanMaxHeaderLength, then it is folded according to RFC 822 specifications.

setSubject

public void setSubject(java.lang.String subject)
                throws IPWorksException

The subject of the mail message (optional).

The string in Subject is sent with a Subject SMTP header to the mail recipient.

If the resulting header is longer thanMaxHeaderLength, then it is folded according to RFC 822 specifications.

IPWorksException

getTimeout

public int getTimeout()

A timeout for the bean.

If the Timeout property is set to 0, all operations will run uninterrupted until successful completion, or an error condition is encountered.

If Timeout is set to a positive value, the bean will wait for the operation to complete before returning control.

The bean will use DoEvents to enter an efficient wait loop during any potential waiting period, making sure that all system events are processed immediately as they arrive. This ensures that the host application does not "freeze" and remains responsive.

If Timeout expires, and the operation is not yet complete, the bean throws an IPWorksException raises an IPWorksException exception .

Please note that by default, all timeouts are inactivity timeouts , i.e. the timeout period is extended by Timeout seconds when data is successfully sent or received.

Optionally, the behaviour of the bean may be changed to absolute timeouts , i.e. the bean will wait for a maximum of Timeout seconds since the beginning of the operation, without extending the timeout period during communications.

This behavior is controlled by theAbsoluteTimeoutconfiguration setting.

The default value for the Timeout property is 60 (seconds).

setTimeout

public void setTimeout(int timeout)
                throws IPWorksException

A timeout for the bean.

If the Timeout property is set to 0, all operations will run uninterrupted until successful completion, or an error condition is encountered.

If Timeout is set to a positive value, the bean will wait for the operation to complete before returning control.

The bean will use DoEvents to enter an efficient wait loop during any potential waiting period, making sure that all system events are processed immediately as they arrive. This ensures that the host application does not "freeze" and remains responsive.

If Timeout expires, and the operation is not yet complete, the bean throws an IPWorksException raises an IPWorksException exception .

Please note that by default, all timeouts are inactivity timeouts , i.e. the timeout period is extended by Timeout seconds when data is successfully sent or received.

Optionally, the behaviour of the bean may be changed to absolute timeouts , i.e. the bean will wait for a maximum of Timeout seconds since the beginning of the operation, without extending the timeout period during communications.

This behavior is controlled by theAbsoluteTimeoutconfiguration setting.

The default value for the Timeout property is 60 (seconds).

IPWorksException

getUser

public java.lang.String getUser()

A user id to login as in the MailServer .

If the User property is set to a non-empty string, then when connecting to the MailServer an AUTH or CRAM-MD5 (depending on the value of AuthMechanism ) command is sent in order to provide authentication information for the user.

setUser

public void setUser(java.lang.String user)
             throws IPWorksException

A user id to login as in the MailServer .

If the User property is set to a non-empty string, then when connecting to the MailServer an AUTH or CRAM-MD5 (depending on the value of AuthMechanism ) command is sent in order to provide authentication information for the user.

IPWorksException

addAttachment

public void addAttachment(java.lang.String fileName)
                   throws IPWorksException

Adds FileName as an attachment.

The Attachments property contains the full list of attachments.

Example (Adding an Attachment)

 Control.AddAttachment("C:\\file1.zip")
 Control.AddAttachment("C:\\file2.zip")
 Control.Send() 

IPWorksException

config

public java.lang.String config(java.lang.String configurationString)
                        throws IPWorksException

Sets or retrieves a beanconfiguration setting.

Config is a generic method available in every bean. It is used to set and retrieveconfiguration settingsfor the bean.

Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the bean, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY , you must call Config("PROPERTY=VALUE") , where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY") . The value will be returned as a string.

IPWorksException

connect

public void connect()
             throws IPWorksException

Connects to the mail relay and sends the SMTP HELO command.

Connects to the mail relay and sends the SMTP HELO command, thus preparing for sending messages. Any number of messages can later be sent using the Send method.

Example (Connect and Send an Email)

 control.MailServer = "MyServer"
 control.From = "me@server.com"
 control.SendTo = "recipient@server.com"
 control.Subject = "My Subject"
 control.MessageText = "This is the message body"
 control.Connect()
 control.Send()
 control.Disconnect() 

IPWorksException

disconnect

public void disconnect()
                throws IPWorksException

Disconnect from the SMTP server.

Disconnects from the mail relay.

IPWorksException

doEvents

public void doEvents()
              throws IPWorksException

Processes events from the internal message queue.

When DoEvents is called, the bean processes any available events. If no events are available, it waits for a preset period of time, and then returns.

IPWorksException

interrupt

public void interrupt()
               throws IPWorksException

Interrupt the current method.

If there is no method in progress, Interrupt simply returns doing nothing.

IPWorksException

processQueue

public void processQueue(java.lang.String queueDir)
                  throws IPWorksException

Sends the messages which have previously been queued into QueueDir .

The PITrail event shows the interaction with the server as messages as are processed.

ProcessQueue looks for in the directory for files with extension ".queued" and starts processing them.

When processing starts, the file extension is changed to ".sending". If an error happens at this stage, the sending process is aborted, and the file extension is changed to ".failed".

If the file is successfully sent, the file is normally deleted, unless theKeepQueueconfiguration setting is set to True, in which case the file extension is instead changed to ".sent" and the queue file is not deleted.

IPWorksException

queue

public java.lang.String queue(java.lang.String queueDir)
                       throws IPWorksException

Queues the message into QueueDir .

The message is queued into a unique file into the directory QueueDir for future processing.

QueueDir must already exist, or an error will be generated.

The method returns the name of the unique queue file created in QueueDir . The file extension is ".queued".

Please refer to the ProcessQueue method for more information on email queue processing.

IPWorksException

resetHeaders

public void resetHeaders()
                  throws IPWorksException

Resets all the message headers to empty.

Resets all the message headers to "" (empty string). Use this property before creating a new message, so that headers from the previous message are not carried over to the next one.

IPWorksException

send

public void send()
          throws IPWorksException

Send the current message and MIME encoded attachment.

If the bean is not connected to the mail relay, a connection is created, the message is sent, and then the connection is closed unless an error occurs.

If the bean is already connected (by use of the Connect method), the connection will remain open after the message is sent. To disconnect, call the Disconnect method.

Example (Send an HTML Email)

 HTMLMailerControl.MailServer = "myserver"
 HTMLMailerControl.SendTo = "recipient@myserver.com"
 HTMLMailerControl.From = "me@myserver.com"
 HTMLMailerControl.Subject = "My Subject"
 HTMLMailerControl.MessageHTML = "  Hello  , my name is  Tom  "
 HTMLMailerControl.Send 

IPWorksException

setMessageHTMLStream

public void setMessageHTMLStream(java.io.InputStream messageStream)
                          throws IPWorksException

Send the current message and MIME encoded attachment.

If the bean is not connected to the mail relay, a connection is created, the message is sent, and then the connection is closed. Unless a ConnectionId is specified, in which case the connection is left open for another bean to use the same connection.

If the bean is already connected (by use of the Connect operation), the connection will remain open after the message is sent. To disconnect, call the Disconnect operation.

Example (Send an HTML Email)

 MailServer = "myserver"
 SendTo = "recipient@myserver.com"
 From = "me@myserver.com"
 Subject = "My Subject"
 MessageHTML = "  Hello  , my name is  Tom  "
 HtmlmailerOperation = htmlmailerOpSend 

IPWorksException

addHtmlmailerEventListener

public void addHtmlmailerEventListener(ipworks.HtmlmailerEventListener l)
                                throws java.util.TooManyListenersException

java.util.TooManyListenersException

removeHtmlmailerEventListener

public void removeHtmlmailerEventListener(ipworks.HtmlmailerEventListener l)