Triggering a process with email

Overview

In addition to the manual, scheduled, and API triggers, the Robot Workforce processes also support triggering runs with emails. You can find the process email trigger configuration using the Configure Process button on the process details page. The email configuration is under the Schedules & Triggers tab. Once you enable the trigger, you will be given a unique email address that is the process's inbox. Sending emails to this address will create work items on the processes input queue.

Configuration Options

Parse email

When enabled, Control Room will parse the email and extract email details to individual work item payload attributes and attachments. For backwards compatibility, this option can be disabled, and the Control Room will not parse the email but forwards the raw MIME message as a work item payload.

Trigger process

This option controls whether Control Room should trigger the process run for newly received emails or not. If the option is disabled, Control Room will not start runs for received emails, and the resulting work items will remain in the input queue.

Work item formats

Parsed email payload

The example below outlines the format for successfully received emails when the Parse email option is enabled.

{
  "id": "1234567890"
  ...
  "payload": {
    "email": {
      "to": [
        {
          "address": "[email protected]",
          "name": "",
        }
      ],
      "from": {
        "address": "[email protected]",
        "name": "Mark the Monkey",
      },
      "cc": [],
      "bcc": [],
      "replyTo": {
        "address": "[email protected]",
        "name": "Mark the Monkey"
      },
      "date": "2022-02-22T06:00:00Z",
      "subject": "A small step for a monkey...",
      "text": "..."
    }
  }
  "files": [
    {
      "id": "12345678",
      "name": "__raw_mail",
      "size": 31223
    },
    {
      "id": "01234abc",
      "name": "__mail.html",
      "size": 440
    },
    {
      "id": "abcd1234",
      "name": "rover-plans.pdf",
      "size": 25435
    },
    {
      "id": "efff5678",
      "name": "flag.png",
      "size": 4096
    }
  ]
}

Payload format for failed email receives

The example below outlines the format for work items resulting from email handling errors.

{
  "id": "1234567890"
  ...
  "payload": {
    "failedEmail": "..."
  },
  "errors": [
    {
      "message": "Payload too large, 150000 bytes, maximum size: 100000"
    }
  ]
}

Unparsed raw payload format (deprecated)

The example below outlines the format for successfully received emails when the Parse email option is disabled. Note that this is a legacy format that has been deprecated. Support for this format will be disabled in the future.

{
  "id": "1234567890"
  ...
  "payload": {
    "rawEmail": "..."
  }
}

Limitations

Email size

The total size of the received email is limited to 40MB. This is the size of the email with all headers, content, and attachments. There are no separate limitations on e.g., individual attachment size.

If the received email size is over the limit the system won't process the email at all and the email will be completely ignored and won't e.g. create the work item with the failedEmail attribute.

April 29, 2022