Pre-processing Functions

Filter and modify webhooks and other processes

EmailEngine allows pre-processing of several actions, such as webhooks posted using the Webhook Routing feature and emails stored in ElasticSearch. The pre-processing function is a small JavaScript code snippet that you can provide to EmailEngine, which runs whenever a triggering event occurs.

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, a 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 you 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:

Specifications

Editor Actions

  • Toggle fullscreen maximizes the editor window. To return to normal view, press the ESC key.
  • Set test payload allows you to set the input payload manually or 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 and async syntax. This is mostly needed for Fetch calls.

Environment Variables

EmailEngine allows defining an environment for the pre-processing scripts. This is a JSON object string you can set either from the Service settings page or via the 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 a 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: