finagle-smtp

This is a minimum implementation of SMTP client for finagle according to RFC5321. Please see the API documentation for information that isn't covered in the introduction below.

Note: There is no API yet in this implementation for creating MIME messages, so the message should be plain US-ASCII text, or converted to such. There is currently no support for any other SMTP extensions, either. This functionality is to be added in future versions.

Usage

Sending an email

The object for instantiating a client capable of sending a simple email is SmtpSimple. For services created with it the request type is EmailMessage, described in EmailMessage.scala.

You can create an email using DefaultEmail class described in DefaultEmail.scala:

    val email = DefaultEmail()
      .from_("[email protected]")
      .to_("[email protected]", "[email protected]")
      .subject_("test")
      .text("first line", "second line") //body is a sequence of lines

Applying the service on the email returns Future.Done in case of a successful operation. In case of failure it returns the first encountered error wrapped in a Future.

Greeting and session

Upon the connection the client receives server greeting. In the beginning of the session an EHLO request is sent automatically to identify the client. The session state is reset before every subsequent try.

Sending independent SMTP commands

The object for instantiating an SMTP client capable of sending any command defined in RFC5321 is Smtp.

For services created with it the request type is Request. Command classes are described in Request.scala.

Replies are differentiated by groups, which are described in ReplyGroups.scala. The concrete reply types are case classes described in SmtpReplies.scala.

This allows flexible error handling:

val res = service(command) onFailure {
  // An error group
  case ex: SyntaxErrorReply => log.error("Syntax error: %s", ex.info)

  // A concrete reply
  case ProcessingError(info) => log,error("Error processing request: %s", info)

  // Default
  case _ => log.error("Error!")
}

// Or, another way:

res handle {
  ...
}

Greeting and session

Default SMTP client only connects to the server and receives its greeting, but does not return greeting, as some commands may be executed without it. In case of malformed greeting the service is closed. Upon service.close() a quit command is sent automatically, if not sent earlier.

License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this software except in compliance with the License.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.