SMTP protocol

This protocol sends an email with optional attachments.

Summary

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

The EmailConnection class provides a simple way to build Connection requests for the SMTP transport, including email 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 email
}

See Sending an e-mail using EmailConnection for more examples.

Request and response format

`POST` operation

Request headers

Request header name	Comments
`Subject`	Email subject text.
`From`	Sender's email address. If not supplied, the primary recipient email address will be used as the sender email address.
`To`	Optional `List` of recipient email addresses. The primary recipient email address (as specified by the request resource target or the `mailto` configuration parameter) will automatically be added.
`Cc`	Optional `List` of CC recipient email addresses.
`Bcc`	Optional `List` of BCC recipient email addresses.
`Content-Type`	Email body MIME type. If not specified, `text/plain; charset=UTF-8` will be 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 will sent to the server as a separate SMTP header.

The values of To, Cc and Bcc headers must be lists of simple, individual email 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 will be assumed to be already encoded to 7-bit ASCII and will be 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 will be 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, the first value will be used. If `charset` not specified, 7-bit ASCII will be 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.	`25`
`mailto`	Override primary recipient email address.	Request target resource name.

Protocol configuration can be applied to the connection request using various mechanism, as described in Configuring protocols.

Example configuration of default hostname for SMTP requests:

/config/connection/defaults/smtp/hostname = "smtp.yourdomain.com"

The SMTP protocol implementation does not support secured SMTP servers using SSL or authentication.