Object Overview

The mail output connector object allows AlchemyPoint Server to send e-mail messages using an intermediary SMTP server. This allows AlchemyPoint to send mail using existing ISP e-mail accounts / SMTP servers.

This object utilizes AlchemyPoint's underlying Connector framework and thus supports a variety of rate limiting and concurrency options.

Example Object Definitions

... directly within the top-level ServerConfiguration object:

Minimal Configuration:

<MailOutputConnector name="MailOut1"
                     hostname="smtp.myisp.com"
                     portNum="25"/>

Overview:

The above example is a mail output connector that accepts 'raw' MailMessages? from a SMTPListener or MailInputConnector. These mail messages are sent to the intermediary SMTP server "smtp.myisp.com" for delivery.

Complex Configuration (all possible attributes shown):

<MailOutputConnector name="MailOut1" tags="mail connector smtp output"
                     description="example output for sending e-mail through an intermediary SMTP server"
                     hostname="smtp.myisp.com"
                     portNum="25"
                     username="myacct@myisp.com"
                     password="mysecret123"
                     useSSL="false"
                     useStartTLS="false"
                     mailFrom="user@testdomain.com"
                     mailTo="someuser@someotherdomain.com"
                     subject="test alert email"
                     messageBody="alert message: "
                     outputTo="messageBody"
                     outputMode="append"
                     disableSubjectOverride="true"
                     disableMailFromOverride="false"
                     disableMailToOverride="true"
                     rateLimitDuration="60"
                     rateLimitPipelineMax="1"
                     connectRateLimit="5"
                     messageRateLimit="5"
                     reconnectAttempts="5"
                     reconnectInterval="60"
                     reconnectExpBackoff="true"/>

Overview:

The above example is a mail output connector that accepts any opaque input from an AlchemyPoint DataSource? (BindingSource? , DispatcherSource? , ProtocolListener? , ProtocolInputConnector? , etc.). This connector crafts an e-mail from "user@testdomain.com" to "someuser@someotherdomain.com" whenever input is received from an AlchemyPoint DataSource? . The e-mail consists of a message with the subject "test alert email" with the contents "alert message: " + whatever opaque data was received from a DataSource? . Mail messages are sent to the intermediary SMTP server "smtp.myisp.com" for delivery.

AlchemyPoint DataSources? sending 'raw' MailMessages? , or DataSources? dispatching multiple key/value pairs in KeyValueMessages? , are both capable of overriding the default 'subject' and 'mailTo' address parameters used by this Connector.

This connector is rate limited at 5 outbound e-mails every 60 seconds, and will attempt to redeliver messages up to 5 times. The first redelivery attempt is made after a 60 second delay, with subsequent attempt delays doubling each time (120 seconds, 240, ...).

Supported Attributes

General Attributes:

• name - (usage: required): Public name of the configuration object. This name must be globally-unique across the entire AlchemyPoint ServerConfiguration definition.

• description - (usage: optional): Textual description of the configuration object.

• tags - (usage: optional): Space-delimited list of one or more tags used to describe the configuration object.

SMTP Attributes:

• hostname - (usage: required): Internet hostname (or IP address) of the SMTP server used by this Connector to send e-mail messages.

• portNum - (usage: required): TCP port (1-65535) of the SMTP server used by this Connector to send e-mail messages.

• username - (usage: optional): The username to utilize when logging into the SMTP server (for SMTP server that require user authentication).

• password - (usage: optional): The password to utilize when logging into the SMTP server (for SMTP server that require user authentication).

• useSSL - (usage: optional, default: "false"): If set to true, the Connector will utilize SSL encryption and authentication when communicating with the SMTP server.

• useStartTLS - (usage: optional, default: "false"): If set to true, the Connector will connect to the SMTP server using plain-text SMTP, but request a secure TLS connection using the "startTLS" protocol command.

Object Attributes:

• mailFrom - (usage: optional): The 'from' address (sender) of e-mail messages sent by this Connector.
  • If 'disableMailFromOverride' is set to 'false', this 'from' address can be overridden by the sender address in received 'raw' MailMessages? , or the 'mailFrom' keyed string value in a received KeyValueMessage? .

• mailTo - (usage: mixed): The 'to' address (recipient) of e-mail messages sent by this Connector.
  • If 'outputTo' is set to 'subject' or 'messageBody', this attribute is required. Otherwise it is optional.
  • If 'disableMailToOverride' is set to 'false', this 'to' address can be overridden by the recipient address in received 'raw' MailMessages? , or the 'mailTo' keyed string value in a received KeyValueMessage? .

• subject - (usage: optional): The 'subject' of e-mail messages sent by this Connector.

• messageBody - (usage: mixed): The 'message body' (main content of message) of e-mail messages sent by this Connector.
  • If 'outputTo' is set to 'subject' or 'mailTo', this attribute is required. Otherwise it is optional.
  • If 'outputTo' is set to 'raw', this attribute is prohibited.

Output Mode Attributes:

• outputTo - (usage: optional, default: "raw"): The internal element within an e-mail message that is updated by this Connector upon receiving AlchemyPoint OpaqueMessage? , MailMessage? , or KeyValueMessage? messages. Supported 'outputTo' values are:
  • mailTo - Received message data is written to the e-mail 'mailTo' address in sent e-mails.
    • If a static 'to' address was specified using the 'mailTo' attribute, it will be rewritten or appended depending on the 'outputMode' setting.
    • Setting ignored on receipt of 'raw' MailMessage? messages.
  • messageBody - Received message data is written to the e-mail 'message body' (main content of message).
    • If a static 'message body' was specified using the 'messageBody' attribute, it will be rewritten or appended depending on the 'outputMode' setting.
    • Setting ignored on receipt of 'raw' MailMessage? messages.
  • subject - Received message data is written to the e-mail 'subject' ('Subject' e-mail header).
    • If a static 'e-mail subject' was specified using the 'subject' attribute, it will be rewritten or appended depending on the 'outputMode' setting.
    • Setting ignored on receipt of 'raw' MailMessage? messages.
  • raw - Connector only accepts 'raw' MailMessages? , not OpaqueMessage? or KeyValueMessage? messages.
    • The 'outputMode' attribute has no effect (it is ignored) when this setting is used.

• outputMode - (usage: optional, default: "append"): The manner in which received OpaqueMessage? or KeyValueMessage? data is written to sent e-mail messages. Supported 'outputMode' values are:
  • append - Received message data is appended to the 'outputTo' element within sent e-mail messages.
  • rewrite - Received message data rewrites the 'outputTo' element (overwriting any static value setting) within sent e-mail messages.

Override Settings Attributes:

• disableMailFromOverride - (usage: optional, default: "false"): If set to 'true', disables the ability for 'raw' MailMessages? or KeyValueMessages? to overwrite the static 'mailFrom' address configured for this Connector.

• disableMailToOverride - (usage: optional, default: "false"): If set to 'true', disables the ability for 'raw' MailMessages? or KeyValueMessages? to overwrite the static 'mailTo' address configured for this Connector.

• disableSubjectOverride - (usage: optional, default: "false"): If set to 'true', disables the ability for 'raw' MailMessages? or KeyValueMessages? to overwrite the static 'subject' mail header configured for this Connector.

Rate Limit Attributes:

• rateLimitDuration - (usage: optional, default: "0"): The duration (in seconds) utilized by both the 'connectRateLimit' and 'messageRateLimit' parameters. A value of "0" disables all rate limits for this Connector.

• connectRateLimit - (usage: optional): The number of TCP connections that may be created by this Connector within the 'rateLimitDuration' period.

• messageRateLimit - (usage: optional): The number of e-mail messages that may be sent by this Connector (possibly within the scope of a single TCP connection) within the 'rateLimitDuration' period.

• rateLimitPipelineMax - (usage: optional): The number of e-mail messages that may be 'pipelined' by this Connector (sent in a single 'bunch' without any messageRateLimit between messages, within the scope of a single TCP connection). This setting is useful for specifying the number of e-mails that may be sent in rapid sequence over a single SMTP connection.
  • The 'rateLimitPipelineMax' setting has an upper bound of 'messageRateLimit' messages. The maximum allowable value for this pipeline setting is the Connector's 'messageRateLimit' setting.

Automatic Reconnect Attributes:

• reconnectAttempts - (usage: optional, default: "0"): The number of times (0-1000) this Connector should attempt to deliver an outbound e-mail message.

• reconnectInterval - (usage: optional, default: "1"): The interval (1+) in seconds that the Connector should delay between redelivery attempts for sent e-mail messages.

• reconnectExpBackoff - (usage: optional, default: "true"): Boolean setting that indicates whether the Connector should exponentially increase the reconnection interval upon each message delivery attempt (60 seconds -> 120 -> 240 -> ...)

Supported Child Configuration Elements

• MailHeaders? - (usage: optional): Listing of one or more mail header definitions. These will be automatically included in any e-mails sent by this Connector (whether crafted from 'raw' MailMessages? , OpaqueMessages? or KeyValueMessages? ).
  • If a received 'raw' MailMessage? contains a header that matches one of the static MailHeaders? definitions, the static definition is used (MailMessage? header is discarded).

• SSLClientConfig - (usage: optional): Specifies local x.509 client certificate, private key, trusted x.509 certificate store, and other SSL-related configuration options.

Issues

Unresolved documentation issues: client ip configuration, timeouts, concurrency