Skip to content

Overview

Concepts and Principles

Development

Overview

IDEs

API Explorer

Releases

Release Notes

TORO Integrate

Coder Studio

Coder Cloud

Bug Reports

Search

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. Supports 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 the tracker
Document Type 'Email' The document type to be registered to the 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, 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 a 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.

More Gloop

The distribution ships with an Integrate Package called examples, which contains services (including the above example) demonstrating more use cases.

Groovy Script as a 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 a 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()
        }
    }
}