ipworks
Class Smtp

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

public class Smtp

extends java.lang.Object

The SMTP bean is used to send Internet mail using the SMTP protocol (the Internet mail standard).

The SMTP bean implements a standard SMTP client as specified in RFC 821. It has a simple plug-and-play interface. It contains a number of properties like SendTo , Subject , From , Cc , BCc , etc. that map directly to the internet mail message headers with the same name (RFC 822). The message text is set in MessageText and/or AttachedFile . Messages are sent by calling the Send method.

The bean supports message delivery to multiple recipients through the SendTo , Cc , and BCc properties. Simply specify the destination email addresses separated by commas.

The interface of the bean is open-ended. New features, including MIME attachments can be supported by using the OtherHeaders property.

A number of events provide feedback during the operation of the bean. The Transfer event is fired during message delivery to show the number of bytes delivered. The PITrail event traces the commands that are sent to the server and the respective replies.

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

Smtp()

Method Summary

void	addSmtpEventListener(ipworks.SmtpEventListener 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.
void	expand(java.lang.String emailAddress) Asks the MailServer to expand a name or mailing list.
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).
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).
HeaderList	getMessageHeaders() Collection of RFC822-encoded headers of the message.
java.lang.String	getMessageHeadersString() String representation of RFC822-encoded headers 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 full text of the message to send (without headers).
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	getReturnPath() Sets the Return-Path to be used for sending email.
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	isAllowExtensions() A switch allowing the bean to use ESMTP features (SMTP extensions).
boolean	isConnected() Shows whether the bean is connected.
boolean	isIdle() The current status of the component.
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	removeSmtpEventListener(ipworks.SmtpEventListener l)
void	resetHeaders() Resets all the message headers to empty.
void	send() Send the current message.
void	sendToTerminalAndEmail() Send to terminal and email.
void	sendToTerminalOnly() Send to terminal only.
void	sendToTerminalOrEmail() Send to terminal or email.
void	setAllowExtensions(boolean allowExtensions) A switch allowing the bean to use ESMTP features (SMTP extensions).
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	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	setMessageId(java.lang.String messageId) The MessageId for the message.
void	setMessageRecipients(MessageRecipientList messageRecipients) The collection of recipients of the message.
void	setMessageStream(java.io.InputStream messageStream) Sets the stream to be uploaded to the server as part of the message.
void	setMessageText(java.lang.String messageText) The full text of the message to send (without headers).
void	setOtherHeaders(java.lang.String otherHeaders) An RFC 822 compliant string consisting of extra headers.
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	setReturnPath(java.lang.String returnPath) Sets the Return-Path to be used for sending email.
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 .
void	verify(java.lang.String emailAddress) Send a Verify request to the SMTP server.

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

Smtp

public Smtp()

Method Detail

isAllowExtensions

public boolean isAllowExtensions()

A switch allowing the bean to use ESMTP features (SMTP extensions).

If AllowExtensions is true, the bean will first send the EHLO greeting to the server and, if that fails, the standard HELO command will be sent.

The property is true by default but may be disabled if it's known in advance that the MailServer doesn't support SMTP extensions.

setAllowExtensions

public void setAllowExtensions(boolean allowExtensions)
                        throws IPWorksException

A switch allowing the bean to use ESMTP features (SMTP extensions).

If AllowExtensions is true, the bean will first send the EHLO greeting to the server and, if that fails, the standard HELO command will be sent.

The property is true by default but may be disabled if it's known in advance that the MailServer doesn't support SMTP extensions.

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

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.

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

getMessageHeaders

public HeaderList getMessageHeaders()

Collection of RFC822-encoded headers of the message.

This property holds the full headers of the message in RFC822 format.

getMessageHeadersString

public java.lang.String getMessageHeadersString()

String representation of RFC822-encoded headers of the message.

This property holds the full headers of the message in RFC822 format.

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 full text of the message to send (without headers).

The MessageText property contains the full text of the message.

It is advisable that the text contained in this property be a collection of lines with lengths less than or equal to 80 bytes separated by CRLF ("\\r\\n") . The text in the message lines must contain 7-bit characters so that the message can be successfully pass through the multitude of mail systems on the Internet.

The bean automatically escapes lines that start with a "." by adding another as specified in RFC 821. The message text is unescaped by the receiving agent, so the process is fully transparent.

setMessageText

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

The full text of the message to send (without headers).

The MessageText property contains the full text of the message.

It is advisable that the text contained in this property be a collection of lines with lengths less than or equal to 80 bytes separated by CRLF ("\\r\\n") . The text in the message lines must contain 7-bit characters so that the message can be successfully pass through the multitude of mail systems on the Internet.

The bean automatically escapes lines that start with a "." by adding another as specified in RFC 821. The message text is unescaped by the receiving agent, so the process is fully transparent.

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

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

getReturnPath

public java.lang.String getReturnPath()

Sets the Return-Path to be used for sending email.

Setting the ReturnPath sets the Return-Path to be used for sending email. If this is not set, the value in the From property is used.

setReturnPath

public void setReturnPath(java.lang.String returnPath)
                   throws IPWorksException

Sets the Return-Path to be used for sending email.

Setting the ReturnPath sets the Return-Path to be used for sending email. If this is not set, the value in the From property is used.

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

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

expand

public void expand(java.lang.String emailAddress)
            throws IPWorksException

Asks the MailServer to expand a name or mailing list.

The resulting response is provided in one or more Expand events (one for each address). The bean will try to connect to the mail relay if it is not already connected.

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.

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 Email)

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

IPWorksException

sendToTerminalAndEmail

public void sendToTerminalAndEmail()
                            throws IPWorksException

Send to terminal and email.

Similar to Send but requests also that the message is sent to the terminal of the user as well, if he is logged on and accepts terminal messages. This method requires that AllowExtensions is set to True and is not supported by all mail relays.

IPWorksException

sendToTerminalOnly

public void sendToTerminalOnly()
                        throws IPWorksException

Send to terminal only.

Similar to Send but requests instead that the message is sent to the user's terminal. An exception with the server's response is raised if the user is not logged in or does not accept terminal messages. This method requires that AllowExtensions is set to True and is not supported by all mail relays.

IPWorksException

sendToTerminalOrEmail

public void sendToTerminalOrEmail()
                           throws IPWorksException

Send to terminal or email.

Similar to Send but requests instead that the message is first sent to the user's terminal. If the user is not logged in or does not accept terminal messages, the message is sent to his mailbox. This method requires that AllowExtensions is set to True and is not supported by all mail relays.

IPWorksException

setMessageStream

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

Sets the stream to be uploaded to the server as part of the message.

If an upload stream is set before the Send method is called, the content of the stream will be read by the bean and uploaded to the server; The stream should be open and normally set to position 0. The bean will automatically close this stream ifCloseStreamAfterTransferis set to true (default). If the stream is closed, you will need to call SetMessageStream again before calling Send again. The content of the stream will be read from the current position all the way to the end.

Note: SetMessageStream and LocalFile will reset the other.

IPWorksException

verify

public void verify(java.lang.String emailAddress)
            throws IPWorksException

Send a Verify request to the SMTP server.

Asks the MailServer to verify the email address provided in the EmailAddress property.

IPWorksException

addSmtpEventListener

public void addSmtpEventListener(ipworks.SmtpEventListener l)
                          throws java.util.TooManyListenersException

java.util.TooManyListenersException

removeSmtpEventListener

public void removeSmtpEventListener(ipworks.SmtpEventListener l)