Email Parser Installation Instructions

How to configure the Self Service Email Parser

Create an App Key

First create an App Key. You'll need a separate App Key for each integrated system

Create an Email Parser Configuration

Create a BigPanda email parser configuration with a POST to the endpoint found in the integration configuration page.

Use the following HTTP headers:

Authorization: Bearer {YOUR TOKEN}
Content-Type: application/json

The JSON payload contains a config object that can contain all or a subset of the following fields:

FieldDescriptionExample
email_formatFormat of email. One of [ plain_text, html ].*"email_format": "plain_text"
allow_list *optionalArray of wildcard strings of allowed sender emails."allow_list": ["*@alertstool.com"]
status *optionalJSON object that can contain configuration of alert status, properties below.
status.default_to *optionalOne of [ critical, warning, acknowledged, unknown ]. Defaults to critical."default_to": "warning"
status.source *optionalThe source for the status extraction. One of [ subject, body ]. Defaults to body."source":"subject"
status.status_map *optionalJSON object that can contain an array of strings per status to match against.**{"critical":["major","very bad"], "ok": ["ok", "clear"], "warning": ["warning"]}
primary_propertyJSON object for configuration of alert's primary property, properties below.
primary_property.nameThe field (tag) name of the primary property."name": "host"
primary_property.sourceThe source for the primary property extraction. One of [ subject, body ]."source": "body"
primary_property.extractionThe regex to extract the primary property from the source."extraction": "(.*)"
primary_property.default_to *optionalThe string to default to if the primary property is not successfully extracted.***"default_to": "general issue"
secondary_property *optionalJSON object for configuration of alert's secondary properties, see primary property properties.
additional_attributes *optionalArray of JSON objects for each additional attribute (tag) to be extracted.[{"name": "region", “source”: “body”, “extraction”: "region: (.*)", “default_to”: “us-west-1”}]

An email received in html format may be processed as plain text if email_format is set to plain_text. In this case, the email will be converted to plain text before tag extraction.

📘

If more than one status is matched, the status will be selected in the following order: ok > critical > warning > acknowledged > unknown.

🚧

If the primary_property.default_to is not configured and the extraction is not successful, the primary property's value will be set to the email's subject

Below is an example of a full payload:

{
   "config":{
      "email_format":"plain_text",
      "status":{
         "default_to":"warning",
         "source":"subject",
         "status_map":{
            "critical":[
               "major",
               "very bad"
            ],
            "ok":[
               "ok",
               "clear"
            ],
            "warning":[
               "warning"
            ]
         }
      },
      "primary_property":{
         "name":"host",
         "source":"body",
         "extraction":"host is (.*)",
         "default_to":"general issue"
      },
      "additional_attributes":[
         {
            "name":"region",
            "source":"body",
            "extraction":"region: (.*)",
            "default_to":"us-west-1"
         },
         {
            "name":"email_body",
            "source":"body",
            "extraction":"([\\s\\S]*)" 
         }
      ]
   }
}

Below is an example of a curl request:

curl -XPOST -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
https://api.bigpanda.io/configurations/alerts/emailparser/$YOUR_ID \
-d '{"config":{"email_format":"plain_text","status":{"default_to":"warning","source":"subject","status_map":{"critical":["major","very bad"], "ok": ["ok", "clear"], "warning": ["warning"]}}, "primary_property": {"name": "host", "source":"body", "extraction":"host is (.*)","default_to":"general issue"}, "additional_attributes": [{"name": "region", "source": "body", "extraction": "region: (.*)", "default_to": "us-west-1"}, {"name": "email_body", "source": "body", "extraction": "([\\s\\S]*)"}]}}'

Configure email alerts to be sent to BigPanda

The output of the curl request in the previous step includes the unique email address generated for this integration. Configure your monitoring tool to send the email alerts to this address.