Vert.x client for sending SMTP emails via a local mail server (e.g.
postfix), by external mail server (e.g. googlemail or aol).
The client supports a few additional auth methods like DIGEST-MD5 and has full support for TLS and SSL and is completely asynchronous. The client supports connection pooling to keep connections open for an specific time to be reused.
Creating a client
You can send mails by creating a client that opens SMTP connections from the local jvm.
The client uses a configuration object, the default config is created as empty object and will connect to localhost port 25, which should be ok in a standard Linux environment where you have Postfix or similar mail server running on the local machine. For all possible properties of the config object, see below.
require 'vertx-mail/mail_client'
config = {
}
mailClient = VertxMail::MailClient.create(vertx, config)
A more elaborate example using a mailserver that requires login via TLS
require 'vertx-mail/mail_client'
config = {
}
config['hostname'] = "mail.example.com"
config['port'] = 587
config['starttls'] = :REQUIRED
config['username'] = "user"
config['password'] = "password"
mailClient = VertxMail::MailClient.create(vertx, config)
Sending mails
Once the client object is created, you can use it to send mails. Since the sending of the mails works asynchronous in vert.x, the result handler will be called when the mail operation finishes. You can start many mail send operations in parallel, the connection pool will limit the number of concurrent operations so that new operations will wait in queue if no slots are available.
A mail message is constructed as JSON. The MailMessage object has properties from, to, cc, bcc, subject, text, html etc. Depending on which values are set, the format of the generated MIME message will vary. The recipient address properties can either be a single address or a list of addresses.
The MIME encoder supports us-ascii (7bit) headers/messages and utf8 (usually quoted-printable) headers/messages
message = {
}
message['from'] = "user@example.com (Example User)"
message['to'] = "recipient@example.org"
message['cc'] = "Another User <another@example.net>"
message['text'] = "this is the plain message text"
message['html'] = "this is html text <a href=\"\">vertx.io</a>"
Attachments can be created by the MailAttachment object using data stored in a Buffer, this supports base64 attachments.
require 'vertx/buffer'
attachment = {
}
attachment['contentType'] = "text/plain"
attachment['data'] = Vertx::Buffer.buffer("attachment file")
message['attachment'] = attachment
When sending the mail, you can provide a AsyncResult<MailResult> handler that will be called when the send operation is finished or it failed.
A mail is sent as follows:
mailClient.send_mail(message) { |result,result_err|
if (result_err == nil)
puts result
else
result_err.print_stack_trace()
end
}
Mail-client data objects
MailMessage properties
Email fields are Strings using the common formats for email with or without real name
-
username@example.com -
username@example.com (Firstname Lastname) -
Firstname Lastname <username@example.com>
The MailMessage object has the following properties
-
fromString representing the From address and the MAIL FROM field -
toString or list of String representing the To addresses and the RCPT TO fields -
ccsame as to -
bccsame as to -
bounceAddressString representing the error address (MAIL FROM), if not set from is used -
textString representing the text/plain part of the mail -
htmlString representing the text/html part of the mail -
attachmentMailAttachment or list of MailAttachment attachments of the message -
headersMultiMap representing headers to be added in addition to the headers necessary for the MIME Message -
fixedHeadersboolean if true, only the headers provided as headers property will be set in the generated message
the last two properties allow manipulating the generate messages with custom headers, e.g. providing a message-id chosen by the calling program or setting different headers than would be generated by default. Unless you know what you are doing, this may generate invalid messages.
MailAttachment properties
The MailAttachment object has the following properties
-
dataBuffer containing the binary data of the attachment -
contentTypeString of the Content-Type of the attachment (e.g. text/plain or text/plain; charset="UTF8", default is application/octet-stream) -
descriptionString describing the attachment (this is put in the description header of the attachment), optional -
dispositionString describing the disposition of the attachment (this is either "inline" or "attachment", default is attachment) -
nameString filename of the attachment (this is put into the disposition and in the contentType headers of the attachment), optional
MailConfig options
The configuration has the following properties
-
hostnamethe hostname of the smtp server to connect to (default is localhost) -
portthe port of the smtp server to connect to (default is 25) -
startTLSStartTLSOptions either DISABLED, OPTIONAL or REQUIRED, default is OPTIONAL -
loginLoginOption either DISABLED, NONE or REQUIRED, default is NONE -
usernameString of the username to be used for login -
passwordString of the password to be used for login -
sslboolean whether to use ssl on connect to the mail server (default is false), set this to use a port 465 ssl connection -
ehloHostnameString to used in EHLO and for creating the message-id, if not set, the own hostname will be used, which may not be a good choice if it doesn’t contain a FQDN or is localhost -
authMethodsString space separated list of allowed auth methods, this can be used to disallow some auth methods or define one required auth method -
keepAliveboolean if connection pooling is enabled (default is true) -
idleTimeoutint timeout in seconds that a connection is kept open after a mail has been sent (default is 300) -
maxPoolSizeint max number of open connections kept in the pool or to be opened at one time (regardless if pooling is enabled or not), default is 10 -
trustAllboolean whether to accept all certs from the server (default is false) -
netClientOptionsNetClientOptions object to be used when connecting to the server port, this allows for example to set a custom keystore to use a self-defined certificate or a "custom" CA
MailResult object
The MailResult object has the following members
-
messageIDthe Message-ID of the generated mail -
recipientsthe list of recipients the mail was sent to