Email Parser Configuration
The Email Parser Configuration API enables you to create and manage email parser configurations, setting specific parsing rules to extract alert data from the subject and body of an email.
Ideal for monitoring tools and systems that do not support REST API, email parser integrations extract alert data such as status, description, and additional properties right from the email's subject or body. The parser supports both text and HTML content.
Each alert should be sent in a separate email.
The parser is not able to parse attachments - all alert data must be in the subject or body of the email.
Configuration for separate sources
A unique email parser must be configured for each source that will be sending emails to BigPanda
Pre-Configuration
Before an email integration can be configured using the Email Parser API, the integration must be created within the UI.
Follow the in-product steps to create a new Alerts API Integration and make note of the app key and integration id.
Once created, the integration can be configured through the Email Parser API
Extraction Rules
Default Rules
There are four pre-defined extraction rules. These rules can be customized, but cannot be deleted. Additional rules to extract additional properties can be configured.
Each rule can be configured to pull from the subject or body of the email.
Alert status
This lookup rule searches in the subject or body for specific strings. If there is a match, the defined status will be populated. If not, the next rule will be run. If none of the rules match, the default value will be populated.
Default mapping rules:
Email Status | BigPanda Status |
|---|---|
“Has been resolved” “resolved” | ok |
“Unknown problem” | warning |
“High severity” | critical |
If none of these are matched, the default status is
critical
Regex Support
A regular expression (regex) can be used to extract status strings.
Primary Property Tag
This tag will be marked as the primary_property in BigPanda.
Mail source
Populated automatically from the “FROM” address and cannot be changed.
Secondary Property Tag (Optional)
This tag will be marked as the secondary_property in BigPanda.
We recommend configuring secondary properties when possible to help connect critical/warning events to their corresponding ok message.
Additional Properties
Custom tags can be extracted as defined during configuration. The following must be defined for each tag:
Tag name - The custom tag must already exist in BigPanda. Tag names must meet the following requirements:
Maximum length of 64 characters.
Starts with a letter from a to z.
Contains only lowercase letters (a-z), numbers (0-9), and some special characters, including underscores ( _ ) and hyphens ( - ) and cannot contain spaces.
Source - Select either Subject or Body.
Default Value - Set a string to function as the tag value if the extraction rule isn’t met.
Extraction rule - The regex rule to extract the value from the email. The extraction rule cannot be empty for any configured tag.
File Limit
The parser can handle emails up to 10 MB
Previewing Sample Alerts
Use the sample email pane to easily preview and configure extraction rules for the parser. Copy the text of a sample email on the left, and the system will generate a sample alert based on the email values and configured settings.
Authorized Sources
Populate this field with the list of email addresses that will be sending emails to this parser. The * character acts as a wildcard. For example, if you would like to include all addresses from a certain domain, you can use *@bigpanda.io.
During configuration, BigPanda will automatically create a recipient address for the integration. As a standard, these email addresses use plus addressing (i.e. bpalerts+<SOMEVALUE>@bigpanda.io)
If your alerting system does not support plus addressing, contact BigPanda Support.
Parameters
The Parser Configuration object schema includes the following attributes:
Parameter | Description | Type |
|---|---|---|
email_format | The format of the email content. Options are: Plain Text or HTML | String |
allow_list | An array of allowed sender emails. Use a wildcard to allow for a range of email addresses. If no address is provided, the parser will accept emails from any source and may lead to false alarms or issues. | Array |
status | Lookup rule to set the alert status. Attributes: default_to - the value to populate if no matches are found. source - is the value in the body or subject? status_map - defines values that map to assigned statuses. Values will be matched in order, stopping at the first match: -critical -warning -ok -acknowledged | Object |
primary_property | Mapping rule for the primary property. Attributes: name - title of property. Default is source - is the value in the body or subject? Default is extraction - regex rule to extract value default_to - value if nothing is extracted | Object |
secondary_property | Mapping rule for the secondary property. Attributes: name - title of property source - is the value in the body or subject extraction - regex rule to extract value default_to - value if nothing is extracted | Object |
additional_attributes | Array of payload field objects to set mapping rules for additional tags. Each object must be defined: Custom Tag Attributes: name - title of property source - is the value in the body or subject? extraction - regex rule to extract value default_to - value if nothing is extracted | Object |
Regex supported
A regular expression (regex) can be used to extract status strings.011
Sample Object
{
"config":
{
"email_format": "plain_text",
"allow_list": [
"string"
],
"status": {
"default_to": "warning",
"source": "subject",
"status_map": {
"critical": [
"major",
"very bad"
],
"warning": [
"warning"
],
"ok": [
"ok",
"clear"
],
"acknowledged": [
"ack"
]
}
},
"primary_property": {
"name": "host",
"source": "body",
"extraction": "host is (.*)",
"default_to": "general issue"
},
"secondary_property": {
"name": "region",
"source": "body",
"extraction": "region (.*)",
"default_to": "us-west-1"
},
"additional_attributes": [
{
"name": "region",
"source": "body",
"extraction": "region: (.*)",
"default_to": "us-west-2"
}
]
}
},
"sample_payload": {
"alerts": [
{
"generatorURL": "https://some-url.io",
"fingerprint": "123456789",
"annotations": {
"description": "This alert is used to check the CPU utilization of this non-existent server",
"runbook_url": "https://runbook.io/cpu-check"
},
"startsAt": "2022-07-05T19:59:25.661Z",
"endsAt": "0001-01-01T00:00:00Z",
"status": "firing",
"labels": {
"severity": "page",
"instance": "bigpanda-server",
"alertname": "BigPanda Test",
"team": "metrics",
"env": "test",
"job": "CPU Check",
"locale": "ca",
"timestamp": "1.657051103137505e+09"
}
}
],
"commonLabels": {
"instance": "bigpanda-server",
"alertname": "BigPanda Test",
"team": "metrics",
"env": "test",
"job": "CPU Check",
"locale": "ca",
"timestamp": "1.657051103137505e+09"
},
"externalURL": "https://external-url.io",
"groupLabels": {
"instance": "bigpanda-server",
"alertname": "BigPanda Test",
"team": "metrics",
"env": "test",
"job": "CPU Check",
"locale": "ca",
"timestamp": "1.657051103137505e+09"
},
"receiver": "bigpanda",
"version": "4",
"commonAnnotations": {
"description": "This alert is used to check the CPU utilization of this non-existent server",
"runbook_url": "https://runbook.io/cpu-check"
},
"status": "firing"
}
}