Pre-processing functions

Filter and modify webhooks and other processes

EmailEngine allows pre-processing of several actions, for example webhooks that are posted using the Webhook Routing feature and emails that are stored in ElasticSearch. The pre-processing function is a small javascript code that you can provide to EmailEngine, and that is run any time a triggering event happens.

In general, there are two types of pre-processing functions:

1. Filter functions

The output from this function determines if the event is processed or discarded. For the filter function to pass, it must return the boolean true value. Any other value or exception will discard the event. For webhooks, the failing filter means that the webhook is not posted, and for Document Store events, it means that the email is not stored in the Document Store.

2. Mapping functions

This function allows to modify the structure of the processed data. You can add or remove properties or completely replace the value.

Here's how the Document Store pre-processing function configuration page looks like:

Specifications

Editor actions

  • Toggle fullscreen maximizes the editor window. To get back to normal view, hit the ESC key
  • Set test payload allows to set the input payload manually or to select an example payload
  • Send webhook preview sends the payload from the preview screen to the specified webhook URL

Variables

  • payload is the event payload. For webhooks, it is the webhook structure where email information is nested under the data property. For Document Store events, it is the email object itself.
  • env is the environment variable – defaults to an empty object if not defined
  • logger is a Pino logger object. It does not provide the full feature set but only the basic logging options like logger.error(...) etc. The log entries are logged to EmailEngine's output log.

Supported APIs

EmailEngine disables most APIs for security reasons when running the pre-processing functions, so in general, only the native JavaScript functions are available. There are some specific Web APIs that are enabled:

  • Fetch to run external web requests. Be aware though, that this might slow down queue processing, so it is not advised to make external requests if you have a system that processes a large number of emails.
  • URL to parse and process URLs

Pre-processing functions support top-level await..async syntax. This is mostly needed for the Fetch calls.

Environment variables

EmailEngine allows defining of an environment for the pre-processing scripts. This is a JSON object string you can set either from the Service settings page or via Settings API using the scriptEnv key.

Once the environment object value is set, it becomes available for all pre-processing scripts as the env object variable.

Defining the environment from the admin page:

Defining the same environment using an Settings API call:

Once you have the environment object set up, you can use it in the filter and map functions as the env variable.

The following filter function only passes if the account id of the email is listed in the provided array.

This mapping function sets a property to the email from the environment object.