Email Sender Output Adapter

Introduction

The Spotfire Streaming Email Sender sends email messages from a StreamBase application to one or more recipients via an SMTP server. Each tuple received by the adapter results in one email message. The email headers and body can be configured in the adapter, such that each email message contains the same header and body values, or passed within tuples to the adapter, such that each email message contains a different set of header and body values. Each header field can be configured independently to derive its value from one of these two sources.

The adapter uses a background thread to compose and send email messages, so it need not be configured to run in a parallel region to avoid performance issues arising from this relatively expensive activity. Set the Outgoing Message Queue Capacity property to a value large enough to accommodate the maximum expected email message burst.

Adapter Properties

This section describes the properties you can set for this adapter, using the various tabs of the Properties view in StreamBase Studio.

Connection Properties Tab

Property Data Type Description
SMTP Client Host string The host name or IP address of the SMTP client. Normally, this property can be left blank, and the name of the local machine on which the adapter is running is sent in the EHLO message to the SMTP server. However, some SMTP servers are configured to require a fully-qualified client host name, in which case this property can be used to satisfy that requirement.
SMTP Server Host string The host name or IP address of the SMTP server.
SMTP Server Port int The TCP port number of the SMTP server.
Use Authentication check box Determines whether authentication is required with the SMTP server.
Username string If Use Authentication is enabled, the username to authenticate with.
Password string If Use Authentication is enabled, the password to authenticate with.
Use SSL check box If Use Authentication is enabled, select this checkbox if the SMTP server requires authenticated, encrypted communication using the Secure Sockets Layer (SSL) protocol.
Outgoing Message Queue Capacity int The number of outgoing email messages that queue before input tuples to the adapter start to back up. The value must be between 1 and 2147483647.
Throttle Error Messages check box Determines whether the adapter suppresses duplicate error messages.
Enable SMTP Debugging check box Determines whether the SMTP messages exchanged by the client and server are displayed.
Enable Event Port check box Enables an output port that emits event tuples when errors occur sending email and, optionally, when email is sent successfully.
Event on Send Success check box If enabled, a tuple is emitted on the event port when an email message is sent successfully.
Log Level INFO Controls the level of verbosity the adapter uses to issue informational traces to the console. This setting is independent of the containing application's overall log level. Available values, in increasing order of verbosity, are: OFF, ERROR, WARN, INFO, DEBUG, TRACE.

Message Properties Tab

Property Data Type Description
From string The name of the schema field from which to retrieve the From email header value, or the From value itself, depending on the setting of the From Contains property.
From Contains radio buttons If set to Schema field name, the value of the From header is retrieved from the schema field specified in the From property. Otherwise, the From property contains the actual From header value to place in all email messages.
Reply To string Optional. The name of the schema field from which to retrieve the Reply To email header value, or the Reply To value itself, depending on the setting of the Reply To Contains property. If omitted, the Reply To header receives the From header value.
Reply To Contains radio buttons If set to Schema field name, the value of the Reply To header is retrieved from the schema field specified in the Reply To property. Otherwise, the Reply To property contains the actual Reply To header value to place in all email messages.
To string Optional. The name of the schema field from which to retrieve the To email header value, or the To value itself, depending on the setting of the To Contains property. If omitted, no recipients are included in the To header. At least one recipient must be included in each message, in either the To, CC, or BCC headers.
To Contains radio buttons If set to Schema field name, the value of the To header is retrieved from the schema field specified in the To property. Otherwise, the To property contains the actual To header value to place in all email messages.
CC string Optional. The name of the schema field from which to retrieve the CC email header value, or the CC value itself, depending on the setting of the CC Contains property. If omitted, no recipients are included in the CC header. At least one recipient must be included in each message, in either the To, CC, and/or BCC headers.
CC Contains radio buttons If set to Schema field name, the value of the CC header is retrieved from the schema field specified in the CC property. Otherwise, the CC property contains the actual CC header value to place in all email messages.
BCC string Optional. The name of the schema field from which to retrieve the BCC email header value, or the BCC value itself, depending upon the setting of the BCC Contains property. If omitted, no recipients are included in the BCC header. At least one recipient must be included in each message, in either the To, CC, or BCC headers.
BCC Contains radio buttons If set to Schema field name, the value of the BCC header is retrieved from the schema field specified in the BCC property. Otherwise, the BCC property contains the actual BCC header value to place in all email messages.
Subject string Optional. The name of the schema field from which to retrieve the email subject, or the subject value itself, depending upon the setting of the Subject Contains property. If omitted, the email message is sent with an empty subject.
Subject Contains radio buttons If set to Schema field name, the value of the email subject is retrieved from the schema field specified in the Subject property. Otherwise, the Subject property contains the actual subject value to place in all email messages.
Body string Optional. The name of the schema field from which to retrieve the email body, or the body value itself, depending upon the setting of the Body Contains property. If omitted, the email message is sent with an empty body.
Body Contains radio buttons If set to Schema field name, the value of the email body is retrieved from the schema field specified in the Body property. Otherwise, the Body property contains the actual body value to place in all email messages.
Content Type string The name of the schema field from which to retrieve the content type or the content type value itself, depending upon the setting of the Content Type Contains property. If omitted, the content type is sent as text/plain.
Content Type Contains radio buttons If set to Schema field name, the content type is retrieved from the schema field specified in the Content Type property. Otherwise, the Content Type property contains the actual content type for all email messages.
Attachments list<string>, list<tuple<string,string,string>>, or list<tuple<blob,string,string,string>>

A list of files to include with each email. These attachments will always be included with each message no matter the content of the attachments field of the incoming tuple.

If the input tuple type is:
  • list<string> then the field is the file name taken from the drive.

  • list<tuple<string,string,string>> then the first field is the file name taken from the drive. The second field is the content type and the third field is the content encoding.

  • list<tuple<blob, string,string,string>> then the first field is the binary data to send, the second field is the file name to display, the third field is the content type and the forth field is the content encoding. If content type is null or empty the default will be used which is 'application/octet-stream'.

Attachments Field string The field in the incoming tuple which contains the list of attachments to send with the email.

X-Headers Properties

Property Data Type Description
X-Headers key-value pairs Each row in this table contains information for an X-header to be sent along with the outgoing email message. The interpretation of the tags and values depends upon to the following two properties.
X-Headers Tags Contains radio buttons If set to Schema field name, the X-header tag is retrieved from the schema field specified in the Key column of the X-Headers property. Otherwise, the Key column of the X-Headers property contains the actual X-header tag.
X-Headers Values Contains radio buttons If set to Schema field name, the X-header value is retrieved from the schema field specified in the Value column of the X-Headers property. Otherwise, the Value column of the X-Headers property contains the actual X-header value.

Typechecking and Error Handling

Typechecking fails if a required property is omitted or if a property is configured to refer to a schema field, but its value does not contain a valid schema field name. In addition, typechecking fails if no recipients (To, CC, or BCC) are specified. This condition is caught at typecheck time only if all three recipient fields are configured with static (non-schema-derived) values.

Runtime errors occur when the configured SMTP server is inaccessible or when invalid values, such as email addresses, are passed in schema fields. The adapter emits an error message and discards the tuple. Duplicate error messages are suppressed if the Throttle Error Messages property is set to true.

Suspend and Resume Behavior

On suspend, the adapter stops processing tuples and sending email messages.

On resumption, the adapter starts processing tuples and sending email messages once again.