The IMAP Agent emits Events when it detects new emails on an IMAP server.

Use the IMAP Agent to automate actions based on received emails, for example: analyze potentially malicious emails for threats; auto-respond to customers based on email subject or body; or alert teammates in Slack when particular emails are received.

Features

  • Check for new emails manually or run on a schedule.
  • In the first visit to a folder, only check for the initial status and do not emit Events.
  • Only emit Events when new emails meet certain conditions.
  • Optionally mark emails as “read” after checking IMAP server.
  • Specify the folder to check for new emails.
  • Keep a list of Message-Id’s for 100 most recent emails, so duplicate emails do not emit multiple events.

Configuration Options

  • host: Enter the host of the IMAP server.
  • username: Enter the username used to authenticate to the IMAP server.
  • password: Enter the password used to authenticate to the IMAP server. Remember, never include sensitive details such as passwords directly in Agent configurations. Instead, use the “credential” widget (see example configuration options below).
  • port: (Optional) Enter the port used to connect to the IMAP server.
  • ssl: (Optional) When this key is set to “true”, the Agent will connect to the IMAP server using SSL.
  • folders: (Is this optional) Define an array of folder names to monitor for new emails.
  • conditions: (Optional) Define an array of conditions which emails should match in order to emit a corresponding Event.
    • subject/body: Specify a regular expression that needs to match the email subject or body in order for an Event to be emitted. Use the (?i) directive for case-insensitive search. Named captures will appear in the “matches” hash in an emitted Event.
    • from/to/cc: Specify a string that needs to match against email addresses extracted from the corresponding header values of each email. Patterns match addresses in a case insensitive manner. Use “*” as a wildcard.
    • is_unread: Setting this to true or false means only mails that are marked as unread or read respectively, are selected. If this key is unspecified or set to null, it is ignored.
    • has_attachment: Setting this to true or false means only mails that does or does not have an attachment are selected. If this key is unspecified or set to null, it is ignored.
  • mark_as_read: (Optional) When this key is set to “true” it will mark detected emails mails as read on the IMAP server.
  • emit_headers: (Optional) Set to ‘true’ to include email headers from the email.
  • disable_ssl_verification: (Optional) Set to ‘true’ to disable ssl verification.
  • expected_update_period_in_days: (Optional) Set this key to the maximum amount of time expected to pass between Events being created by this Agent. If this period passes without any Events being emitted, the Agent will be flagged as “Not Working”.

Emitted Events

Events emitted by the IMAP Agent look similar to the below:

{
  "message_id": "1688375064.8603887.1514928714437@example.com",
  "folder": "INBOX",
  "subject": "This is the subject of the email",
  "from": "bob@example.com",
  "to": [
    "alice@example.com"
  ],
  "cc": [
     "carol@example.com"
  ],
  "date": "2018-01-01T10:10:00+00:00",
  "mime_type": "text/plain",
  "body": "This is the body of the email.",
  "matches": {
  },
  "has_attachment": true,
  "attachments": [
  {
    "filename": "hello.txt",
    "guid": "dee73fe0-044f-4e2d-873e-e6850debc03a",
    "md5": "aba2d86ed17f587eb6d57e6c75f64f05",
    "sha256": "807126cbae47c03c99590d081b82d5761e0b9c57a92736fc8516cf41bc564a7d",
    "sizeinbytes": 1578,
    "base64encodedcontents": "ug4AtAnNIbgBTM0hVGhpc=="
  }
  ]        
}

Example Configuration Options

Create Events for all emails from the Inbox of a GMail/GSuite account:

{
    "host": "imap.gmail.com",
    "username": "alice@gmail.com",
    "password": "{% credential GMAIL %}",
    "ssl": true,
    "folders": [
        "INBOX"
    ],
    "conditions": {
    },
    "expected_update_period_in_days": "1"
}

Create Events for emails sent to an Office365 account where the subject contains “Urgent” (case-insensitive):

{
    "host": "outlook.office365.com",
    "username": "alice@outlook.com",
    "password": "{% credential OUTLOOK %}",
    "ssl": true,
    "folders": [
        "INBOX"
    ],
    "conditions": {
       "subject": "(?i)urgent"
    },
    "expected_update_period_in_days": "10"
}

Create Events for emails from any @example.com address which also include an attachment:

{
    "host": "outlook.office365.com",
    "username": "alice@outlook.com",
    "password": "{% credential OUTLOOK %}",
    "ssl": true,
    "folders": [
        "INBOX"
    ],
    "conditions": {
       "from": "*@example.com",
       "has_attachment": true
    },
    "expected_update_period_in_days": "10"
}