SMTP protocol

This protocol sends an e-mail with optional attachments.

Protocol summary

Name
smtp
Description
Sends an e-mail using SMTP and MIME encoding.
Resource name
Can contain the primary recipient e-mail address or can be overridden using mailto protocol configuration parameter.
Operations
POST - send e-mail.

The EmailConnection class provides a simple way to build Connection requests for the smtp protocol implementation, including e-mail attachments.

Example usage

The following example uses the EmailConnection API to send a simple e-mail message:

try {
    EmailConnection email = new EmailConnection("you@projectzero.org");
    email.setFromAddress("me@projectzero.org");
    email.setSubject("Hello you!");
    email.setContent("This is the e-mail body.");
    email.send();
} catch (Exception e) {
    // Failed to send e-mail
}
  • See Sending an e-mail using EmailConnection for more examples using the EmailConnection API.
  • You can also use the sendEmail activity to send an e-mail using the smtp protocol implementation from a flow.

Request and response format

This section details the headers and body types for the requests and responses of the supported operations.

POST operation

The POST operation sends an e-mail to a SMTP server. The request body becomes the body of the e-mail message.

Request headers

Request header name Comments
Subject e-mail subject text.
From Sender's e-mail address. If not supplied, the primary recipient e-mail address is used as the sender's e-mail address.
To Optional List of recipient e-mail addresses. The primary recipient e-mail address (as specified by the request resource target or the mailto configuration parameter) is automatically added.
Cc Optional List of CC recipient e-mail addresses.
Bcc Optional List of BCC recipient e-mail addresses.
Content-Type e-mail body MIME type. If not specified, text/plain; charset=UTF-8 is assumed.
MIME-Version Simple applications must leave this header unset.
Other headers Any other headers to be sent with the SMTP message. If the request header has multiple values, each value is sent to the server as a separate SMTP header.
  • The values of To, Cc and Bcc headers must be lists of simple, individual e-mail addresses. Addresses must be of the form user@domain.com only (real name annotations are not supported). Multiple addresses must be represented as multiple values in the lists (comma-separated lists of addresses are not supported).
  • The MIME-Version header should only be set by advanced, MIME-aware applications and connection handlers. If the following conditions are all true then the body is assumed to be already encoded into 7-bit ASCII and is transmitted without further MIME processing:
    • MIME-Version is specified.
    • Content-Type header value begins with multipart/mixed.
    • The request body is not an instance of MultipartBody.
  • If the request body is an instance of MultipartBody then the values of the following request headers are replaced with values appropriate for the MIME encoded request body:
    • MIME-Version
    • Content-Type
    • Content-Transfer-Encoding

Request body

Request body type Comments
String or Reader Encodes character data for SMTP transmission using MIME, according to charset in Content-Type header. If Content-Type has multiple values then the first value is used. If charset not specified then 7-bit ASCII is assumed.
byte[] or InputStream Encodes binary data for SMTP transmission using MIME.
MultipartBody Encode multi-part body using MIME.
Other types Calls toString() and processes result as String.

Response headers

No response headers defined.

Response body

String containing final response message from SMTP server.

Configuration

Parameter Description Default
hostname SMTP server hostname. localhost
port SMTP server port number. Port 465 if smtpsConfig is set, otherwise port 25.
mailto Override primary recipient e-mail address. Request target resource name.
smtpsConfig SMTPS configuration name. None set. (Unencrypted SMTP connection)
userid AUTH PLAIN user ID. None set. (Unauthenticated SMTP connection)
password AUTH PLAIN password. (XOR strings are supported) None set.
connectionTimeout Connection timeout, in seconds. 15 seconds.
readTimeout Socket read timeout, in seconds. 60 seconds.
  • If the userid configuration parameter is supplied, the userid and password values are sent to the SMTP server, using the AUTH PLAIN authentication mechanism. The connection will fail if the SMTP server rejects the supplied credentials or does not support the AUTH PLAIN authentication mechanism.
  • If the value of smtpsConfig is either null or the empty string then an unencrypted socket connection will be used to connect to the SMTP server. If the value contains a SMTPS configuration name, the named configuration will be used to establish a SSL socket connection to SMTP server (SMTPS). The default value of the port parameter is 25 for SMTP and 465 for SMTPS.
  • Protocol configuration can be applied to the connection request using various mechanism, as described in Configuring protocols.

In the following example, a default SMTP server is set for the smtp protocol:

/config/connection/defaults/smtp/hostname = "smtp.projectzero.org"

With no further configuration, the specified SMTP server will be contacted on port 25, using an unencrypted connection and no authentication.

The next example contains a default configuration for a secure SMTP server:

/config/connection/defaults/smtp/hostname = "smtp.projectzero.org"
/config/connection/defaults/smtp/userid = "user1"
/config/connection/defaults/smtp/password = "password1"
/config/connection/defaults/smtp/smtpsConfig = "defaultConfig"

Using this configuration an SMTPS connection will be established to port 465 of the specified server, using the predefined defaultConfig SSL configuration. The user ID and password will be sent to the SMTP server to authenticate the connection.

SMTPS configuration

By setting a value for the smtpsConfig protocol configuration parameter, you can specify that an SSL socket is to be used to connect to the SMTP server (SMTPS). The value of smtpsConfig names a SMTPS configuration to be used for the connection.

The zero.core module contains a predefined SMTPS configuration, which checks that the SMTPS server presents a valid certificate signed by one of a selection of well-known certificate authorities. To use this configuration, the value of smtpsConfig must be set to defaultConfig. The defaultConfig configuration does not present a client certificate to the remote server.

You can configure a custom SMTPS configuration using your own trust store and key store. An SMTPS configuration is specified using the key /config/connection/smtps/ configName, as demonstrated in the following example:

/config/connection/smtps/mySmtpsConfig = {
    "trustStore" : "config/truststore.jks",
    "trustStorePassword" : "password",
    "trustStoreType" : "JKS"
}

The above configuration can be selected by setting smtpsConfig value to mySmtpsConfig.

The SSL configurations defined under /config/connection/smtps/ configName can contain the following properties:

Property Description Notes
trustStore File name of trust store to be used to validate server identity. Required.
trustStorePassword Trust store password. (XOR strings are supported) Required.
trustStoreType Trust store type. Required.
keyStore File name of key store containing client certificate. Optional, default is no client certificate.
keyStorePassword Key store password. (XOR strings are supported) Required if keyStore is specified.
keyStoreType Key store type. Required if keyStore is specified.
disableTrustVerification If true, the outbound connection does not perform any checks to validate the identity of the remote server. Optional, default value is false
  • See the SSL configuration topic for more information about valid key store and trust store type values.
  • The smtp protocol implementation supports secured connections to an SMTP server over an SSL socket (SMTPS). The STARTTLS mechanism for securing SMTP connections is not supported.

Version 1.1.30763