# Mail Binding

The Mail binding provides support for sending mails from rules.

# Supported Things

There are three things: smtp, imap and pop3 which represents respective servers.

# Thing Configuration

# SMTP Server (`smtp`)

There are two mandatory parameters hostname and sender.

The hostname may contain an IP address or a FQDN like smtp.gmail.com. The sender must be a valid mail address used as sender address for mails.

The security, port, username and password parameters are optional.

The security parameter defines the transport security and can be set to PLAIN (default), STARTTLS or SSL (for implicit SSL/TLS). The port parameter is used to change the default ports for the SMTP server. Default ports are 25 (for PLAIN and STARTTLS) and 465 (for SSL). For authentication, username and password can be supplied. If one or both are empty, no authentication data is provided to the SMTP server during connect.

# IMAP Server (`imap`) / POP3 Server (`pop3`)

There is one mandatory parameter: hostname. The hostname may contain an IP address or a FQDN like mail.gmail.com. For authentication username and password also need to be supplied.

The refresh, security, port, username and password parameters are optional.

The refresh parameter is the time in seconds between two refreshes of the thing's channels. If omitted, the default of 60s is used. The security parameter defines the transport security and can be set to PLAIN (default), STARTTLS or SSL (for implicit SSL/TLS). The port parameter is used to change the default ports for the SMTP server. Default ports are 143 (for PLAIN and STARTTLS) and 993 (for SSL) in the case of imap or 110 (for PLAIN and STARTTLS) and 995 (for SSL) in the case of pop3.

# Channels

There are no channels for the smtp thing. The imap and pop3 things can be extended with mailcount-type channels.

# Type `mailcount`

Each channel has two parameters: folder and type. The folder is mandatory and denotes the folder name on the given account. You can either use the root folder like (e.g. "INBOX") or a sub directory of your structure (e.g. "INBOX.Sent" or "INBOX.Junk"). The type parameter can be UNREAD or TOTAL (default). Channels with type UNREAD give the number on unread mails in that folder.

# Full Example

mail.things:

Thing mail:smtp:samplesmtp [ hostname="smtp.example.com", sender="mail@example.com", security="SSL", username="user", password="pass" ]

Thing mail:imap:sampleimap [ hostname="imap.example.com", security="SSL", username="user", password="pass" ] {
    Channels:
        Type mailcount : inbox_total [ folder="INBOX", type="TOTAL" ]
        Type mailcount : inbox_unread [ folder="INBOX", type="UNREAD" ]
}

mail.items:

Number InboxTotal  "INBOX [%d]"        { channel="mail:imap:sampleimap:inbox_total" }
Number InboxUnread "INBOX Unread [%d]" { channel="mail:imap:sampleimap:inbox_unread" }

mail.sitemap:

sitemap demo label="Main Menu"
{
    Frame {
        Text item=InboxTotal
        Text item=InboxUnread
    }
}

# Rule Action

This binding includes rule actions for sending email. Six different actions available:

boolean success = sendMail(String recipient, String subject, String text)
boolean success = sendMail(String recipient, String subject, String text, String URL)
boolean success = sendMail(String recipient, String subject, String text, List<String> URL)
boolean success = sendHtmlMail(String recipient, String subject, String htmlContent)
boolean success = sendHtmlMail(String recipient, String subject, String htmlContent, String URL)
boolean success = sendHtmlMail(String recipient, String subject, String htmlContent, List<String> URL)

The sendMail(...) send a plain text mail (with attachments if supplied). The sendHtmlMail(...) send a HTML mail (with attachments if supplied).

Both functions return a boolean as the result of the operation.

recipient can be a single address (mail@example.com) or a list of addresses, concatenated by a comma (mail@example.com, mail2@example.com).

Since there is a separate rule action instance for each smtp thing, this needs to be retrieved through getActions(scope, thingUID). The first parameter always has to be mail and the second is the full Thing UID of the SMTP server that should be used. Once this action instance is retrieved, you can invoke the action method on it.

Please note: All strings are expected to be UTF-8 encoded. Using different character sets may produce unwanted results.

Examples:

val mailActions = getActions("mail","mail:smtp:samplesmtp")
val success = mailActions.sendMail("mail@example.com", "Test subject", "This is the mail content.")
success = mailActions.sendMail("mail1@example.com, mail2@example.com", "Test subject", "This is the mail content sent to multiple recipients.")

import java.util.List

val List<String> attachmentUrlList = newArrayList(
  "http://some.web/site/snap.jpg&param=value",
  "file:///tmp/201601011031.jpg")
val mailActions = getActions("mail","mail:smtp:sampleserver")
mailActions.sendHtmlMail("mail@example.com", "Test subject", "<h1>Header</h1>This is the mail content.", attachmentUrlList)

# Mail Headers

The binding allows one to add custom e-mail headers to messages that it sends. For example if you want e-mails sent by this binding to be grouped into a "threaded view" in your email client, you must provide an e-mail "Reference" header, which acts as the key for grouping messages together. Headers can be added inside a rule by calling the mailActions.addHeader() method before calling the respective mailActions.sendMail() method. See the example below.

rule "Send Mail with a 'Reference' header; for threaded view in e-mail client"
when
    ...
then
    val mailActions = getActions("mail","mail:smtp:sampleserver")
    mailActions.addHeader("Reference", "<unique-thread-identifier>")
    mailActions.sendMail("mail@example.com", "Test subject", "Test message text")
end

Note: in the case of the "Reference" header, the <unique-thread-identifier> has to be an ASCII string enclosed in angle brackets.

Caught a mistake or want to contribute to the documentation? Edit this page on GitHub (opens new window)

← MagentaTV MAX! →