Email Alerts API Guide

The Email Alerts API enables you to configure and manage email performance alerts for your account. You can create up to 8 alerts per account to monitor metrics like Usage and receive notifications when thresholds are reached.

Permissions Required

To access Email Alerts API endpoints, the user must have the following permissions:

EmailConfiguration.Alerts_Create
EmailConfiguration.Alerts_Delete
EmailConfiguration.Alerts_Read
EmailConfiguration.Alerts_Update

Fact Sheet

Feature	Support	Remark
Maximum Alerts	8	Per logical account limit
Logical Account ID	Yes	Must be a valid GUID, cannot be empty
Alert Names	Yes	Custom names for easy identification
Alert Metrics	Yes	Usage
Threshold Operators	Yes	Over (>), Below (<), Equal (=)
Multiple Recipients	Yes	Comma-separated email addresses
Alert Management	Yes	Create, Read, Update, Delete operations

Managing Email Alerts

The Email Alerts API uses a logical account ID (GUID) to identify and manage alerts for specific accounts. Each alert monitors a specific metric and sends notifications to designated recipients when thresholds are met.

API Endpoints

1. List All Alerts

Retrieve all alerts configured for a logical account.

Required Permission: EmailConfiguration.Alerts_Read

GET /v1/account/{logicalAccount}/alerts/list

Successful Response

{
    "isSuccess": true,
    "statusCode": 200,
    "message": "Alerts found.",
    "data": [
        {
            "id": 1,
            "logicalAccountId": "123e4567-e89b-12d3-a456-426614174000",
            "alertName": "High Open Rate Alert",
            "metric": "Usage",
            "threshold": ">90",
            "recipient": "[email protected], [email protected]",
            "createdDate": "2024-01-15T10:30:00Z",
            "updatedDate": "2024-01-15T10:30:00Z"
        }
    ]
}

2. Create New Alert

Create a new alert for monitoring email metrics.

Required Permission: EmailConfiguration.Alerts_Create

POST /v1/account/{logicalAccount}/alerts/create
Content-Type: application/json

{
    "alertName": "Low Open Rate Alert",
    "metric": "Usage",
    "threshold": "<50",
    "recipient": "[email protected], [email protected]"
}

Successful Response

{
    "isSuccess": true,
    "statusCode": 200,
    "message": "Successfully inserted new email alert.",
    "data": 2
}

Maximum Limit Error Response

{
    "isSuccess": false,
    "statusCode": 400,
    "message": "Maximum alert limit reached, cannot add more alerts.",
    "data": -1
}

3. Update Existing Alert

Update an existing alert configuration.

Required Permission: EmailConfiguration.Alerts_Update

PUT /v1/account/{logicalAccount}/alerts/update/{id}
Content-Type: application/json

{
    "alertName": "Updated Open Rate Alert",
    "metric": "Usage",
    "threshold": ">85",
    "recipient": "[email protected], [email protected]"
}

Successful Response

{
    "isSuccess": true,
    "statusCode": 200,
    "message": "Updated email alert",
    "data": 1
}

4. Delete Alert

Delete an existing alert.

Required Permission: EmailConfiguration.Alerts_Delete

DELETE /v1/account/{logicalAccount}/alerts/delete/{id}

Successful Response

{
    "isSuccess": true,
    "statusCode": 200,
    "message": "Successfully deleted email alert with id 1",
    "data": 1
}

Alert Not Found Error Response

{
    "isSuccess": false,
    "statusCode": 400,
    "message": "Alert not found or already deleted.",
    "data": -1
}

Request Parameters

Path Parameters

Parameter	Type	Required	Description
Logical Account	GUID	Yes	Unique identifier for the logical account
id	int32	Yes	Alert ID (for update/delete operations only)

Request Body Fields

Field	Type	Required	Description
Alert Name	string	Yes	Name of the alert
metric	string	Yes	Usage
threshold	string	Yes	Threshold with operator (e.g., ">90", "<50", "=75")
recipient	string	Yes	Email addresses (comma-separated for multiple)

Threshold Operators

Operator	Symbol	Description
Over	>	Alert when metric is above threshold
Below	<	Alert when metric is below threshold
Equal	=	Alert when metric equals threshold

Status Codes

Status Code	Description
200	OK: Request processed successfully
400	Bad Request: Invalid request or maximum limit reached
404	Not Found: Alert or account not found
500	Internal Server Error: Server-side error occurred

Error Handling

All error responses follow a consistent format:

{
    "isSuccess": false,
    "statusCode": 400,
    "message": "Error description",
    "data": null
}

Best Practices

Alert Limit: Remember the 8-alert limit per account. Plan your alerts strategically.
Threshold Values: Use percentage values (0-100) for thresholds.
Multiple Recipients: Use comma-separated email addresses for multiple notifications. You can add max 5 recipients per alert.
Meaningful Names: Use descriptive alert names for easy identification.
Monitor Performance: Regularly review and update alert thresholds based on your email performance trends.

Example Use Cases

High Performance Alert

Monitor when open rates exceed expectations:

{
    "alertName": "Excellent Campaign Performance",
    "metric": "Usage",
    "threshold": ">95",
    "recipient": "[email protected]"
}

Deliverability Issue Alert

Monitor for delivery problems:

{
    "alertName": "High Bounce Rate Warning",
    "metric": "Usage",
    "threshold": ">10",
    "recipient": "[email protected], [email protected]"
}

Spam Monitoring Alert

Watch for spam complaints:

{
    "alertName": "Spam Complaint Monitor",
    "metric": "Usage",
    "threshold": ">1",
    "recipient": "[email protected]"
}