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:

Field	Description	Example
`email_format`	Format of email. One of [ `plain_text`, `html` ].*	`"email_format": "plain_text"`
`allow_list` *optional	Array of wildcard strings of allowed sender emails.	`"allow_list": ["*@alertstool.com"]`
`status` *optional	JSON object that can contain configuration of alert status, properties below.
`status.default_to` *optional	One of [ `critical`, `warning`, `acknowledged`, `unknown` ]. Defaults to `critical`.	`"default_to": "warning"`
`status.source` *optional	The source for the status extraction. One of [ `subject`, `body` ]. Defaults to `body`.	`"source":"subject"`
`status.status_map` *optional	JSON object that can contain an array of strings per status to match against.**	`{"critical":["major","very bad"], "ok": ["ok", "clear"], "warning": ["warning"]}`
`primary_property`	JSON object for configuration of alert's primary property, properties below.
`primary_property.name`	The field (tag) name of the primary property.	`"name": "host"`
`primary_property.source`	The source for the primary property extraction. One of [ `subject`, `body` ].	`"source": "body"`
`primary_property.extraction`	The regex to extract the primary property from the source.	`"extraction": "(.*)"`
`primary_property.default_to` *optional	The string to default to if the primary property is not successfully extracted.***	`"default_to": "general issue"`
`secondary_property` *optional	JSON object for configuration of alert's secondary properties, see primary property properties.
`additional_attributes` *optional	Array 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.