Email Adapter
  • 02 May 2024
  • Dark
    Light
  • PDF

Email Adapter

  • Dark
    Light
  • PDF

Article summary

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
Changing your password will log you out immediately. Use the new password to log back in.
First name must have atleast 2 characters. Numbers and special characters are not allowed.
Last name must have atleast 1 characters. Numbers and special characters are not allowed.
Enter a valid email
Enter a valid password
Your profile has been successfully updated.