Email Adapter

Updated on 02 May 2024

Dark

Light
PDF

Article summary

Did you find this summary helpful?

Thank you for your feedback

⚠ WARNING:

IAP adapter-email was deprecated in the 2023.1 release and scheduled for removal in the 2024.1 release. The replacement is an Open Source Email Adapter available in the Itential Pre-Built Collection. See "Adapter Email" in the Product Notice Deprecations for more detail.

Properties

The Email adapter can be used to deliver email notifications to end users. Currently, notifications are triggered based on job completion or from custom tasks within a workflow.

Property	Type	Default	Description
`host`	String	`127.0.0.1`	Hostname or IP address to connect to.
`port`	Number	`587`	The port to connect to (defaults to 587 if `secure` is false, or 465 if `secure` is true). Must be a number in the range 1 - 65535.
`auth.user`	String		The default username to send from.
`auth.pass`	String		The password for the default username.
`authMethod`	String	`PLAIN`	Required. Defines the preferred authentication method. Authentication methods currently supported include: • `PLAIN` - Sends username and password credentials to server with a PLAIN header. • `LOGIN` - Uses username and password with a LOGIN header. • `CRAM-MD5` - Expects to get a challenge hash from the email server to test against the username and password.
`secure`	Boolean	`false`	Use TLS.
`ignoreTLS`	Boolean		If this is true and `secure` is false then TLS is not used even if the server supports STARTTLS extension.
`requireTLS`	Boolean		If this is true and `secure` is false then the adapter tries to use STARTTLS even if the server does not advertise support for it. If the connection cannot be encrypted then message is not sent.
`tls.isServer`	Boolean		The SSL/TLS protocol is asymmetrical; TLSSockets must know if they are to behave as a server or a client. If true the TLS socket will be instantiated as a server.
`tls.requestCert`	Boolean		If true the server will request a certificate from clients that connect and attempt to verify that certificate.
`tls.rejectUnauthorized`	Boolean		If not false the server will reject any connection which is not authorized with the list of supplied CAs. This option only has an effect if `tls.requestCert` is true.
`tls.requestOCSP`	Boolean		If true specifies that the OCSP status request extension will be added to the client hello and an OCSPResponse event will be emitted on the socket before establishing a secure communication.
`name`	String		Optional hostname of the client used for identifying to the server; defaults to hostname of the machine.
`localAddress`	String		The local interface to bind to for network connections.
`connectionTimeout`	Number		How many milliseconds to wait for the connection to establish.
`greetingTimeout`	Number		How many milliseconds to wait for the greeting after connection is established.
`socketTimeout`	Number		How many milliseconds of inactivity to allow.
`subscriptions`	Array	`['email-event-unseen']`	Listen to emails in inbox and publish an event in IAP on unread messages. The only supported event currently is `email-event-unseen`.
`incomingEmailSizeLimit`	Number	`10000`	Maximum size allowed for incoming email when listening to emails. Minimum is `0` bytes. Maximum is `1000000` bytes ~ 1MB.

Note:

Configure the email adapter to be a member of the notification broker.

Minimal Configuration Example

{
  "id": "email",
  "type": "Email",
  "properties": {
    "host": "127.0.0.1",
    "port": 25,
    "secure": false
  },
  "brokers": [ "notification" ]
}

Production Configuration Example

{
  "id": "email",
  "type": "Email",
  "properties": {
    "host": "mail.example.com",
    "port": 587,
    "secure": true,
    "authMethod": "PLAIN",
    "auth": {
      "user": "pronghorn",
      "pass": "$ENC93f88824437dfe5784c7570f99d7251f878a2284aed6449259"
    }
  },
  "brokers": [ "notification" ]
}

SMTP Services and IMAP Transport

If you want to send emails, the Email adapter uses Nodemailer for SMTP connections to several well-known service providers. A list of the supported services can be found at the Nodemailer site.

If you want to receive emails and start a job from an email, an IMAP conection to the email server is required.

Example Configurations

The Email adapter can be configured using Nodemailer or by using a host name and port number. Two examples are presented below.

Example 1

In this example, Outlook365 is the service provider being used in the configuration.

{
    "id": "email",
    "type": "Email",
    "properties": {
      "service": "Outlook365",
      "auth": {
        "user": "username",
        "pass": "password"
      },
      "secure": false
    },
    "brokers": [
      "notification"
    ],
    "groups": []
  }

Example 2

In this example, the host name is configured for outlook.office365.com and the port number is 993. A service provider is not used.

    "id": "email",
    "type": "Email",
    "properties": {
      "host": "outlook.office365.com",
      "port": 993,
      "auth": {
        "user": "username",
        "pass": "password"
      },
      "secure": false
    },
    "brokers": [
      "notification"
    ],
    "groups": []
  }

Sending Attachments

You can add attachments to an email message. To do so, use an array of name and content objects. Below is a sample input for the mailwithOptions task to send attachments.

Example

{
  "from": "example@itential.com",
  "to": [
    "example@itential.com",
    "secondRecipient@itential.com"
  ],
  "subject": "Successful Device Deployment",
  "body": "Your device successfully deployed with the following details...",
  "displayName": "IAP",
  "cc": [
    "example@itential.com"
  ],
  "bcc": [
    "example@itential.com"
  ],
  "attachments": [
    {
      "name": "Attachment.txt",
      "content": "Text inside of attached file..."
    },
    {
      "name": "Attachment.txt",
      "content": "Text inside of attached file..."
    }
  ]
}

Was this article helpful?

What's Next

Event Service Configuration

Table of contents

Properties
SMTP Services and IMAP Transport
Sending Attachments