Email endpoint
The email endpoint enables developers to write applications that react to messages received in a mail server. Martini periodically checks the configured email and invokes the service if a new, unread email has been received.
Properties
General configuration
Property | Default | Description |
---|---|---|
Name | (required) | The name of the endpoint. |
Service | (required) | The service to execute when the endpoint is triggered. |
Run As | Anonymous |
The user to run the service in behalf of. This is logged to Tracker. |
Document Type | <Name of endpoint type> | The document type to be used when adding documents to Tracker as this endpoint is triggered. |
Auto Start | true |
Whether or not to automatically start the endpoint upon package startup. |
Log To Tracker | false |
Flag determining whether executions should be logged to Tracker. |
Replicated | true |
If this endpoint is configured on a Martini instance that's running in a cluster, replicated will determine whether to run the endpoint on all instances, or only the elected leader node in the cluster. When this is checked, all instances will run the endpoint. When it's unchecked, only the leader node will run the endpoint. |
Email-specific configuration
Property | Default | Description |
---|---|---|
Host | (required) | The email server to connect to. |
Port | 993 |
The server port number. |
Username | (required) | The email address used to login. |
Password | (required) | The password used to login. |
Polling Interval | 1 |
The interval in seconds, which stipulates how often Martini checks the inbox. |
Use SSL | true |
Flag to determine whether the connection uses SSL. |
Type | IMAP |
The email protocol to use. Supported protocols: IMAP and POP3 . |
Delete email on receive | false |
Flag determining whether the received email should be deleted after the service is invoked. |
Send Service response as reply | false |
Flag determining whether the output of the service is to be used as a reply body. |
Send reply on error | false |
Flag determining whether the exception thrown by the service, if any, be sent back as the reply body. |
Auto-populate configuration available for popular email services
You can use the Choose button to populate the form with popular configurations such as GMail, Outlook, and Yahoo.
Reply properties
If "Send Service response as reply" or "Send reply on error" is enabled, additional properties for configuring the reply account is requested:
Property | Default | Description |
---|---|---|
Host | (required) | The email server to connect to. |
Port | 1 |
The server port number. |
Username | (required) | The email address used to login. |
Password | (required) | The password used to login. |
From | (required) | The sender of the email. If none is provided, the value of the Username field is used. |
SSL/TLS | true |
Flag to determine whether the connection uses SSL. |
Auto-populate configuration available for popular email services
You can use the Choose button to populate the reply form with popular configurations such as Amazon SES, GMail, Mailgun, Mandrill, Outlook, Sendgrid, and Yahoo.
Service
When the endpoint is triggered, the following variables are exposed to the configured service:
General parameters
Name | Type | Description |
---|---|---|
$trackerId |
java.lang.String |
The Tracker document internal ID. If the endpoint was configured to not track, this value will be null . |
$tracker |
io.toro.martini.tracker.Tracker |
The Tracker object. If the endpoint was configured to not track, this value will be null . |
martiniPackage |
MartiniPackage |
The Martini package that contains the endpoint. |
parameters |
java.util.Map |
A map containing all the endpoint specific parameters. |
properties |
java.util.Map |
A map containing containing all the properties associated with the endpoint. |
Email-specific parameters
Name | Type | Description |
---|---|---|
message |
javax.mail.Message |
The message that triggered this endpoint. |
to |
javax.mail.Address[] |
The addresses where the email was sent to. |
cc |
javax.mail.Address[] |
The addresses where the email was CC'd to. |
bcc |
javax.mail.Address[] |
The addresses where the email was BCC'd to. |
from |
javax.mail.Address[] |
The addresses where the email was sent from. |
fromAddress |
java.lang.String |
The first email address in the from array. |
replyTo |
javax.mail.Address[] |
The addresses where the email should be replied to. |
subject |
java.lang.String |
The subject of the email. |
headers |
java.util.List< javax.mail.Header > |
The email headers. |
If the message
variable is of type MimeMessage
at runtime (which is the case more often than not), additional variables are exposed
to the service:
Name | Type | Description |
---|---|---|
attachments |
java.util.List< javax.activation.DataSource > |
The list of attachments in the email. |
contentType |
java.lang.String |
Content type of the email body. Values are html and text . |
body |
java.lang.String |
The email body. |
bodyParts |
java.util.List< javax.activation.DataSource > |
The list of body parts in the email. |
content |
java.lang.String |
The email body (alias for content ). |
file |
java.nio.file.Path |
A local file pointing to the first attachment in the email, if exists. |
filename |
java.lang.String |
The absolute path of file . |
inputStream |
java.io.InputStream |
An open InputStream , pointing to the file . The stream is automatically closed after the service executes. |
bytes |
byte[] |
Contains all file data. This variable is only created if your method has a parameter that matches the name (therefore scripts will never have this variable since they don't declare variables). |
Examples
Gloop as service
Consider this application using Gloop. This reads the attachments from an email.
(2) Iterates over the attachments
variable provided by the endpoint when the service is invoked.
(3) Logs each attachment and its contents.
Want more examples?
The distribution ships with a Martini package called examples
, which
contains services (including the above example) demonstrating more use cases.
Groovy script as service
Consider this Groovy script that simply prints the available variables in the context:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
|
When the endpoint is triggered - in this case, an email is sent to the configured mail address - the console prints something similar to the example below:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
|
Groovy method as service
The following example logs the content and name of each attachment from the received email:
1 2 3 4 5 6 7 8 |
|