Skip to content

Home

Introduction

Development

Overview

IDEs

Services

Service manager

API Explorer

Email endpoint

The email endpoint enables developers to write integrations that react to messages received in a mail server. TORO Integrate periodically checks the configured email and invokes the service if a new, unread email is received.

Properties

Property Default Description
Host (required) The email server to connect to.
Port (required) The server port number.
Protocol (required) The email protocol to use. Supported protocols: IMAP and POP3.
Username (required) The email address used to login.
Password (required) The password used to login.
Service (required) The service to execute when the endpoint is triggered.
Polling Interval (required) The interval in seconds, at which TORO Integrate checks the inbox.
Use SSL true Flag to determine whether the connection uses SSL.
Run As Anonymous The user to run the service in behalf of. This is logged to Tracker.
Log to Tracker false Flag determining whether executions should be logged to Tracker.
Document Type Email The document type to be registered to Tracker when this endpoint is triggered.
Delete email on receive false Flag determining whether the received email be deleted after the service is invoked.
Send Service response as reply false Flag determining whether the output of the service be used as a reply body.
Send reply on error false Flag determining whether the exception thrown by the service, if any, would be sent back as reply body.

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 (required) The server port number.
Username (required) The email address used to login.
Password (required) The password used to login.
Use SSL true Flag to determine whether the connection uses SSL.

Service

When the endpoint is triggered, the following variables are exposed to the configured service:

Name Type Description
parameters java.util.Map Contains all the variables below.
esbPackage ESBPackage The Integrate package that contains this endpoint.
properties java.util.Map Contains all the properties associated with the endpoint.
context org.quartz.JobExecutionContext The Quartz context.
jobDataMap org.quartz.JobDataMap The Quartz job data map.
job org.quartz.Job The Quartz job.
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.
internalId java.lang.String Tracker internal ID. If the endpoint was configured to not track, this value will be null.

If the message variable is of type MimeMessage at runtime (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.
content java.lang.String The email body (alias for content).
file java.io.File 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 integration using Gloop. This reads the attachments from an email.

Attachment-reading service

(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 an Integrate 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
[
    'properties',
    'context',
    'jobDataMap',
    'job',
    'message',
    'to',
    'cc',
    'bcc',
    'from',
    'fromAddress',
    'replyTo',
    'subject',
    'internalId',

    'attachments',
    'contentType',
    'body',
    'inputStream',
    'reader' ].each { 

    println "$it\t : " + this[it]   
}

When the endpoint is triggered - in this case, an email is sent to the configured mail address - the console prints accordingly:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
properties   : [ <ommitted> ]
context  : JobExecutionContext: <ommitted>
jobDataMap   : [ <ommitted> ]
job  : io.toro.integrate.core.endpoint.impl.email.EmailJobWrapper@57ba8c74
message  : org.springframework.integration.mail.AbstractMailReceiver$IntegrationMimeMessage@6e2794bf
to   : [recipient@mail.com]
cc  : []
bcc  : []
from     : [Awesome Developer <awesome-developer@mail.com>]
fromAddress  : awesome-developer@mail.com
replyTo  : [Awesome Developer <awesome-developer@mail.com>]
subject  : Hi!
internalId   : null
attachments  : []
contentType  : html
body     : <div dir="ltr">How's the integration going?</div>...<ommitted>
inputStream  : null

Groovy method as service

The following example logs each statement contents from the received email:

1
2
3
4
5
6
7
8
class Reader {

    def readAttachments( def attachments ) {
        attachments.each {
            "Attachment ${it.name} has content ${it.inputStream.text}".info()
        }
    }
}