Skip to content

API Docs - v1.0.11

Sink

email (Sink)

The email sink uses 'smtp' server to publish events via emails. It can be published events in 'text', 'xml' or 'json' formats. The user can define email sink parameters in either 'deployment yaml' file or stream definition. So that email source checks whether parameters are given in stream definition or 'ymal' file respectively. If it is not given in both places, then default values are taken for the optional parameters. If user need to configure server system parameters which are not given as options in stream definition then it is needed to define them in 'yaml' file under email sink properties. (Refer link: https://javaee.github.io/javamail/SMTP-Transport to more information about smtp server parameters). Further, some email account required to enable 'access to less secure apps' option (for gmail account you can enable it via https://myaccount.google.com/lesssecureapps).

Syntax

@sink(type="email", username="<STRING>", address="<STRING>", password="<STRING>", host="<STRING>", port="<INT>", ssl.enable="<BOOL>", auth="<BOOL>", content.type="<STRING>", subject="<STRING>", to="<STRING>", cc="<STRING>", bcc="<STRING>", @map(...)))

QUERY PARAMETERS

Name Description Default Value Possible Data Types Optional Dynamic
username Username of the email account which is used to send emails (e.g: 'abc' is the username for abc@gmail.com). STRING No No
address Address of the email account which is used to send emails. STRING No No
password Password of the email account. STRING No No
host Host name of the smtp server (e.g. host name for a gmail account : 'smtp.gmail.com'). The default value 'smtp.gmail.com' is only valid if email account is a gmail account. smtp.gmail.com STRING Yes No
port The port which is used to create the connection. '465' the default value is only valid is ssl enable INT Yes No
ssl.enable Whether the connection should be established through secure connection or not. The value can be either 'true' or 'false'. If it is 'true' then the connection is establish through 493 port which is secure connection. true BOOL Yes No
auth Whether to use AUTH command or not, while authenticating. If true, then attempt to authenticate the user using the AUTH command. true BOOL Yes No
content.type Content type can be either 'text/plain' or 'text/html'. text/plain STRING Yes No
subject Subject of the mail which has to be send. STRING No Yes
to Address of the 'to' recipients. If there are more than to recipients, then addresses can be given as a comma separated list. STRING No Yes
cc Address of the 'cc' recipients. If there are more than cc recipients, then addresses can be given as a comma separated list. None STRING Yes No
bcc Address of the 'bcc' recipients. If there are more than bcc recipients, then addresses can be given as a comma separated list. None STRING Yes No

System Parameters

Name Description Default Value Possible Parameters
mail.smtp.ssl.trust If set, and a socket factory hasn't been specified, enables use of a MailSSLSocketFactory. If set to "", all hosts are trusted. If set to a whitespace separated list of hosts, those hosts are trusted. Otherwise, trust depends on the certificate the server presents. String
mail.smtp.connectiontimeout Socket connection timeout value in milliseconds. infinite timeout Any Integer
mail.smtp.timeout Socket I/O timeout value in milliseconds. infinite timeout Any Integer
mail.smtp.from Email address to use for SMTP MAIL command. This sets the envelope return address. Defaults to msg.getFrom() or InternetAddress.getLocalAddress(). Valid email address
mail.smtp.localport Local port number to bind to when creating the SMTP socket. Defaults to the port number picked by the Socket class. Any Integer
mail.smtp.ehlo If false, do not attempt to sign on with the EHLO command. true true or false
mail.smtp.auth.login.disable If true, prevents use of the AUTH LOGIN command. false true or false
mail.smtp.auth.plain.disable If true, prevents use of the AUTH PLAIN command. false true or false
mail.smtp.auth.digest-md5.disable If true, prevents use of the AUTH DIGEST-MD5 command. false true or false
mail.smtp.auth.ntlm.disable If true, prevents use of the AUTH NTLM command false true or false
mail.smtp.auth.ntlm.domain The NTLM authentication domain. None Valid NTLM authentication domain name
mail.smtp.auth.ntlm.flags NTLM protocol-specific flags. See http://curl.haxx.se/rfc/ntlm.html#theNtlmFlags for details. None Valid NTLM protocol-specific flags.
mail.smtp.dsn.notify The NOTIFY option to the RCPT command. None Either NEVER, or some combination of SUCCESS, FAILURE, and DELAY (separated by commas).
mail.smtp.dsn.ret The RET option to the MAIL command. None Either FULL or HDRS.
mail.smtp.sendpartial If set to true, and a message has some valid and some invalid addresses, send the message anyway, reporting the partial failure with a SendFailedException. If set to false (the default), the message is not sent to any of the recipients if there is an invalid recipient address. false true or false
mail.smtp.sasl.enable If set to true, attempt to use the javax.security.sasl package to choose an authentication mechanism for login. false true or false
mail.smtp.sasl.mechanisms A space or comma separated list of SASL mechanism names to try to use. None
mail.smtp.sasl.authorizationid The authorization ID to use in the SASL authentication. If not set, the authentication ID (user name) is used. username Valid ID
mail.smtp.sasl.realm The realm to use with DIGEST-MD5 authentication. None
mail.smtp.quitwait If set to false, the QUIT command is sent and the connection is immediately closed. If set to true (the default), causes the transport to wait for the response to the QUIT command. false true or false
mail.smtp.reportsuccess If set to true, causes the transport to include an SMTPAddressSucceededException for each address that is successful. false true or false
mail.smtp.socketFactory If set to a class that implements the javax.net.SocketFactory interface, this class will be used to create SMTP sockets. None Socket Factory
mail.smtp.socketFactory.class If set, specifies the name of a class that implements the javax.net.SocketFactory interface. This class will be used to create SMTP sockets. None
mail.smtp.socketFactory.fallback If set to true, failure to create a socket using the specified socket factory class will cause the socket to be created using the java.net.Socket class. true true or false
mail.smtp.socketFactory.port Specifies the port to connect to when using the specified socket factory 25 Valid port number
mail.smtp.ssl.protocols Specifies the SSL protocols that will be enabled for SSL connections. None The property value is a whitespace separated list of tokens acceptable to the javax.net.ssl.SSLSocket.setEnabledProtocols method.
mail.smtp.starttls.enable If true, enables the use of the STARTTLS command (if supported by the server) to switch the connection to a TLS-protected connection before issuing any login commands. false true or false
mail.smtp.starttls.required If true, requires the use of the STARTTLS command. If the server doesn't support the STARTTLS command, or the command fails, the connect method will fail. false true or false
mail.smtp.socks.host Specifies the host name of a SOCKS5 proxy server that will be used for connections to the mail server. None
mail.smtp.socks.port Specifies the port number for the SOCKS5 proxy server. This should only need to be used if the proxy server is not using the standard port number of 1080. 1080 valid port number
mail.smtp.auth.ntlm.disable If true, prevents use of the AUTH NTLM command false true or false
mail.smtp.mailextension Extension string to append to the MAIL command. None
mail.smtp.userset If set to true, use the RSET command instead of the NOOP command in the isConnected method. In some cases sendmail will respond slowly after many NOOP commands; use of RSET avoids this sendmail issue. false true or false

Examples EXAMPLE 1

@sink(type='email', @map(type ='json'), username='sender.account', address='sender.account@gmail.com',password='account.password',subject='Alerts from Wso2 Stream Processor',to='{{email}}',)define stream fooStream (email string, loginId int, name string);

Following example illustrates how to publish events using the email sinkusing mandatory parameters. As in the example, it publishes events come from the fooStream in json format via email sink to the given 'to' recipients. The email is sent by the sender.account@gmail.com via secure connection.

EXAMPLE 2

@sink(type='email', @map(type ='json'), subject='Alerts from Wso2 Stream Processor',to='{{email}}',)define stream fooStream (email string, loginId int, name string);

Following example illustrates how to configure the query parameters and system parameters in the deployment ymal file.
 Corresponding parameters need to be configure under name:'email' and namespace:'sink' as follows

siddhi:
  extensions:
    -
      extension:
        name:'email'
        namespace:'sink'
        properties:
          username:sender.account
          address:sender.account@gmail.com
          address:sender.account@gmail.com

As in the example, it publishes events comefrom the fooStream in json format via email sink to the given 'to' recipients. The email is sent by the sender.account@gmail.com via secure connection.

EXAMPLE 3

@sink(type='email', @map(type ='json'), username='sender.account', address='sender.account@gmail.com',password='account.password',host='smtp.gmail.com',port='465',ssl.enable='true',auth='true',content.type='text/html',subject='Alerts from Wso2 Stream Processor-{{name}}',to='to1.account@gmail.com, to2.account@gmail.com',cc='cc1.account@gmail.com, cc2.account@gmail.com',bcc='bcc1.account@gmail.com)define stream fooStream (name string, age int, country string);

Following example illustrates how to publish events using the email sink. According to the example, it publishes events come from the fooStream in xml format via email sink as a text/html message to the given to,cc and bcc recipients using a secure connection. name in the subject attribute will be the value of the name parameter in the corresponding output event

Source

email (Source)

Email source allows user to receive events via emails. Email source can be configured using 'imap' or 'pop3' server to receive events. This allows user to filter the messages which satisfy the given criteria under 'search term' option. The user can define email source parameters in either 'deployment yaml' file or stream definition. So that email source checks whether parameters are given in stream definition and 'ymal' file respectively. If it is not given in both places, then default values are taken if defaults values are available. If user need to configure server system parameters which are not given as options in stream definition then it is needed to define them in 'yaml' file under email source properties. (Refer link: https://javaee.github.io/javamail/IMAP-Store , https://javaee.github.io/javamail/POP3-Store to more information about imap and pop3 server system parameters).

Syntax

@source(type="email", username="<STRING>", password="<STRING>", store="<STRING>", host="<STRING>", port="<INT>", folder="<STRING>", search.term="<STRING>", polling.interval="<LONG>", action.after.processed="<STRING>", folder.to.move="<STRING>", content.type="<STRING>", ssl.enable="<BOOL>", @map(...)))

QUERY PARAMETERS

Name Description Default Value Possible Data Types Optional Dynamic
username user name of the email account. (e.g. wso2mail is the username of wso2mail@gmail.commail account. STRING No No
password password of the email account STRING No No
store Store type that used to receive emails. it can be either imap or pop3. imap STRING Yes No
host Host name of the server (e.g. host name for a gmail account with imap store : 'imap.gmail.com'). The default value imap.gmail.com' is only valid if email account is a gmail account with imap enable. If store type is 'imap' then default value is 'imap.gmail.com' and if store type is 'pop3' thendefault value is 'pop3.gmail.com'. STRING Yes No
port The port which is used to create the connection. '993' the default value is valid only if store is imap and ssl enable INT Yes No
folder Name of the folder to fetch email. INBOX STRING Yes No
search.term Option which includes conditions as a key value pairs to search emails. String search term should define ':' separated key and value with ',' separated key value pairs. Currently, this string search term only supported keys: subject, from, to, bcc, and cc. As an example: subject:DAS , from:carbon , bcc:wso2 string search term create a search term instance which filter emails contain 'DAS' in the subject, 'carbon' in the from address and 'wso2' in one of the bcc addresses. It does sub string matching which is case insensitive. But if '@' contains in the given value except for 'subject' key, then it check whether address is equal or not. As a example from: abc@ string search term check whether 'from' address is equal to 'abc' before '@' Symbol. None STRING Yes No
polling.interval Interval that email source should poll the account to check for new mails arrivals in seconds. 600 LONG Yes No
action.after.processed Action that email source should carry out for the processed mail. FLAGGED : set the flag as falgged. SEEN : set the flag as read. ANSWERED : set the flag as answered. DELETE : delete tha mail after the polling cycle. MOVE : move the the mail to the folder given in folder.to.move. If folder is pop3, then only option available is 'DELETE NONE STRING Yes No
folder.to.move The name of the folder, which mail has to move after processing.If the action after process is 'MOVE' then it is mandatory to define the folder to move. STRING No No
content.type Content type of the email. It can be either 'text/plain' or 'text/html.' text/plain STRING Yes No
ssl.enable If it is 'true' then use a secure port to establish the connection. The possible values are 'true or false. true BOOL Yes No

System Parameters

Name Description Default Value Possible Parameters
mail.imap.partialfetch Controls whether the IMAP partial-fetch capability should be used true true or false
mail.imap.fetchsize Partial fetch size in bytes. 16K value in bytes
mail.imap.peek If set to true, use the IMAP PEEK option when fetching body parts, to avoid setting the SEEN flag on messages. Defaults to false. Can be overridden on a per-message basis by the setPeek method on IMAPMessage. false true or false
mail.imap.connectiontimeout Socket connection timeout value in milliseconds. This timeout is implemented by java.net.Socket. infinity timeout Any Integer value
mail.imap.timeout Socket read timeout value in milliseconds. This timeout is implemented by java.net.Socket. infinity timeout Any Integer value
mail.imap.writetimeout Socket write timeout value in milliseconds. This timeout is implemented by using a java.util.concurrent.ScheduledExecutorService per connection that schedules a thread to close the socket if the timeout expires. Thus, the overhead of using this timeout is one thread per connection. infinity timeout Any Integer value
mail.imap.statuscachetimeout Timeout value in milliseconds for cache of STATUS command response. 1000ms Time out in miliseconds
mail.imap.appendbuffersize Maximum size of a message to buffer in memory when appending to an IMAP folder. None Any Integer value
mail.imap.connectionpoolsize Maximum number of available connections in the connection pool. 1 Any Integer value
mail.imap.connectionpooltimeout Timeout value in milliseconds for connection pool connections. 45000ms Any Integer
mail.imap.separatestoreconnection Flag to indicate whether to use a dedicated store connection for store commands. true true or false
mail.imap.auth.login.disable If true, prevents use of the non-standard AUTHENTICATE LOGIN command, instead using the plain LOGIN command. false true or false
mail.imap.auth.plain.disable If true, prevents use of the AUTHENTICATE PLAIN command. false true or false
mail.imap.auth.ntlm.disable If true, prevents use of the AUTHENTICATE NTLM command. false true or false
mail.imap.proxyauth.user If the server supports the PROXYAUTH extension, this property specifies the name of the user to act as. Authenticate to the server using the administrator's credentials. After authentication, the IMAP provider will issue the PROXYAUTH command with the user name specified in this property. None Valid string value
mail.imap.localaddress Local address (host name) to bind to when creating the IMAP socket. Defaults to the address picked by the Socket class. Valid string value
mail.imap.localport Local port number to bind to when creating the IMAP socket. Defaults to the port number picked by the Socket class. Valid String value
mail.imap.sasl.enable If set to true, attempt to use the javax.security.sasl package to choose an authentication mechanism for login. false true or false
mail.imap.sasl.mechanisms A space or comma separated list of SASL mechanism names to try to use. None Valid string value
mail.imap.sasl.authorizationid The authorization ID to use in the SASL authentication. If not set, the authentication ID (user name) is used. Valid string value
mail.imap.sasl.realm The realm to use with SASL authentication mechanisms that require a realm, such as DIGEST-MD5. None Valid string value
mail.imap.auth.ntlm.domain The NTLM authentication domain. None Valid string value
The NTLM authentication domain. NTLM protocol-specific flags. None Valid integer value
mail.imap.socketFactory If set to a class that implements the javax.net.SocketFactory interface, this class will be used to create IMAP sockets. None Valid SocketFactory
mail.imap.socketFactory.class If set, specifies the name of a class that implements the javax.net.SocketFactory interface. This class will be used to create IMAP sockets. None Valid string
mail.imap.socketFactory.fallback If set to true, failure to create a socket using the specified socket factory class will cause the socket to be created using the java.net.Socket class. true true or false
mail.imap.socketFactory.port Specifies the port to connect to when using the specified socket factory. Default port is used when not set. 143 Valid Integer
mail.imap.ssl.checkserveridentity If set to true, check the server identity as specified by RFC 2595. false true or false
mail.imap.ssl.trust If set, and a socket factory hasn't been specified, enables use of a MailSSLSocketFactory.If set to '', all hosts are trusted.If set to a whitespace separated list of hosts, those hosts are trusted.Otherwise, trust depends on the certificate the server presents. Valid String
mail.imap.ssl.socketFactory If set to a class that extends the javax.net.ssl.SSLSocketFactory class, this class will be used to create IMAP SSL sockets. None SSL Socket Factory
mail.imap.ssl.socketFactory.class If set, specifies the name of a class that extends the javax.net.ssl.SSLSocketFactory class. This class will be used to create IMAP SSL sockets. None Valid String
mail.imap.ssl.socketFactory.port Specifies the port to connect to when using the specified socket factory. the default port will be used-993 valid port number
mail.imap.ssl.protocols Specifies the SSL protocols that will be enabled for SSL connections. The property value is a whitespace separated list of tokens acceptable to the javax.net.ssl.SSLSocket.setEnabledProtocols method. None Valid string
mail.imap.starttls.enable If true, enables the use of the STARTTLS command (if supported by the server) to switch the connection to a TLS-protected connection before issuing any login commands. false true or false
mail.imap.socks.host Specifies the host name of a SOCKS5 proxy server that will be used for connections to the mail server. None Valid String
mail.imap.socks.port Specifies the port number for the SOCKS5 proxy server. This should only need to be used if the proxy server is not using the standard port number of 1080. 1080 Valid String
mail.imap.minidletime This property sets the delay in milliseconds. 10 milliseconds time in seconds (Integer)
mail.imap.enableimapevents Enable special IMAP-specific events to be delivered to the Store's ConnectionListener. If true, unsolicited responses received during the Store's idle method will be sent as ConnectionEvents with a type of IMAPStore.RESPONSE. The event's message will be the raw IMAP response string. false true or false
mail.imap.folder.class Class name of a subclass of com.sun.mail.imap.IMAPFolder. The subclass can be used to provide support for additional IMAP commands. The subclass must have public constructors of the form public MyIMAPFolder(String fullName, char separator, IMAPStore store, Boolean isNamespace) and public MyIMAPFolder(ListInfo li, IMAPStore store) None Valid String
mail.pop3.connectiontimeout Socket connection timeout value in milliseconds. Infinite timeout Integer value
mail.pop3.timeout Socket I/O timeout value in milliseconds. Infinite timeout Integer value
mail.pop3.message.class Class name of a subclass of com.sun.mail.pop3.POP3Message None Valid String
mail.pop3.localaddress Local address (host name) to bind to when creating the POP3 socket. Defaults to the address picked by the Socket class. Valid String
mail.pop3.localport Local port number to bind to when creating the POP3 socket. Defaults to the port number picked by the Socket class. Valid port number
mail.pop3.apop.enable If set to true, use APOP instead of USER/PASS to login to the POP3 server, if the POP3 server supports APOP. APOP sends a digest of the password rather than the clear text password. false true or false
mail.pop3.socketFactory If set to a class that implements the javax.net.SocketFactory interface, this class will be used to create POP3 sockets. None Socket Factory
mail.pop3.socketFactory.class If set, specifies the name of a class that implements the javax.net. SocketFactory interface. This class will be used to create POP3 sockets. None Valid String
mail.pop3.socketFactory.fallback If set to true, failure to create a socket using the specified socket factory class will cause the socket to be created using the java.net.Socket class. false true or false
mail.pop3.socketFactory.port Specifies the port to connect to when using the specified socket factory. Default port Valid port number
mail.pop3.ssl.checkserveridentity If set to true, check the server identity as specified by RFC 2595. false true or false
mail.pop3.ssl.trust If set, and a socket factory hasn't been specified, enables use of a MailSSLSocketFactory. If set to '', all hosts are trusted.If set to a whitespace separated list of hosts, those hosts are trusted.Otherwise, trust depends on the certificate the server presents. Valid String
mail.pop3.ssl.socketFactory If set to a class that extends the javax.net.ssl.SSLSocketFactory class, this class will be used to create POP3 SSL sockets. None SSL Socket Factory
mail.pop3.ssl.checkserveridentity If set to true, check the server identity as specified by RFC 2595. false true or false
mail.pop3.ssl.trust If set, and a socket factory hasn't been specified, enables use of a MailSSLSocketFactory.If set to '*', all hosts are trusted.If set to a whitespace separated list of hosts, those hosts are trusted. trust depends on the certificate the server presents. Valid String
mail.pop3.ssl.socketFactory If set to a class that extends the javax.net.ssl.SSLSocketFactory class, this class will be used to create POP3 SSL sockets. None SSL Socket Factory
mail.pop3.ssl.socketFactory.class If set, specifies the name of a class that extends the javax.net.ssl.SSLSocketFactory class. This class will be used to create POP3 SSL sockets. None Valid String
mail.pop3.ssl.socketFactory.p Specifies the port to connect to when using the specified socket factory. 995 Valid Integer
mail.pop3.ssl.protocols Specifies the SSL protocols that will be enabled for SSL connections. The property value is a whitespace separated list of tokens acceptable to the javax.net.ssl.SSLSocket.setEnabledProtocols method. None Valid String
mail.pop3.starttls.enable If true, enables the use of the STLS command (if supported by the server) to switch the connection to a TLS-protected connection before issuing any login commands false true or false
mail.pop3.starttls.required If true, requires the use of the STLS command. If the server doesn't support the STLS command, or the command fails, the connect method will fail. false true or false
mail.pop3.socks.host Specifies the host name of a SOCKS5 proxy server that will be used for connections to the mail server. None Valid String
mail.pop3.socks.port Specifies the port number for the SOCKS5 proxy server. None Valid String
mail.pop3.disabletop If set to true, the POP3 TOP command will not be used to fetch message headers. false true or false
mail.pop3.forgettopheaders If set to true, the headers that might have been retrieved using the POP3 TOP command will be forgotten and replaced by headers retrieved as part of the POP3 RETR command. false true or false
mail.pop3.filecache.enable If set to true, the POP3 provider will cache message data in a temporary file rather than in memory. Messages are only added to the cache when accessing the message content. Message headers are always cached in memory (on demand). The file cache is removed when the folder is closed or the JVM terminates. false true or false
mail.pop3.filecache.dir If the file cache is enabled, this property can be used to override the default directory used by the JDK for temporary files. None Valid String
mail.pop3.cachewriteto Controls the behavior of the writeTo method on a POP3 message object. If set to true, and the message content hasn't yet been cached, and ignoreList is null, the message is cached before being written. Otherwise, the message is streamed directly to the output stream without being cached. false true or false
mail.pop3.keepmessagecontent If this property is set to true, a hard reference to the cached content will be kept, preventing the memory from being reused until the folder is closed or the cached content is explicitly invalidated (using the invalidate method). false true or false

Examples EXAMPLE 1

@source(type='email', @map(type='xml'), username='receiver.account', password='account.password',)define stream inputStream (name string, age int, country string);

Following example illustrates how to receive events in xml format using email source. In this example only mandatory parameters are defined in the in the stream definition. For other parameters default values are taken. since search term is not defined, it poll and take all new messages in the inbox folder

EXAMPLE 2

@source(type='email', @map(type='xml'), username='receiver.account', password='account.password',store = 'imap',host = 'imap.gmail.com',port = '993',searchTerm = 'subject:Stream Processor, from: from.account@ , cc: cc.account',polling.interval='500',action.after.processed='DELETE',content.type='text/html,)define stream inputStream (name string, age int, country string);

Following example illustrates how to receive events in xml format using email source. The email source polls the mail account in every 500 seconds to check whether new mails has been arrived and processes new mails only if if it satisfy the properties given under email search term (email messages which come fromfrom.account@.<host name>, contains cc.account in cc receipts list, and Stream Processor words in the mail subject) In the example, action after processes is defined as the DELETE, so that after processing the event, corresponding mail is deleted from the mail folder.