Alerts

Retrieve alerts for your organization's monitored domains.

List Alerts

GET /api/v1/alerts

Returns a paginated list of alerts for your organization.

Query Parameters

Parameter	Type	Description
page	integer	Page number (default: 1)
limit	integer	Results per page, max 100 (default: 20)
domainId	string	Filter by domain ID
severity	string	Filter by severity: info, warning, or critical
unreadOnly	boolean	Only return unread alerts (default: false)

Response

{
  "data": [
    {
      "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "domainId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "domainName": "example.com",
      "type": "score_change",
      "severity": "warning",
      "title": "Security score decreased",
      "message": "The security score for example.com dropped from 85 to 72",
      "metadata": {
        "previousScore": 85,
        "newScore": 72
      },
      "read": false,
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "hasMore": false
    }
  }
}

Alert Types

Type	Description
score_change	Domain security score changed significantly
score_threshold	Score dropped below configured threshold
dns_change	DNS record change detected
report_failure	DMARC report showed authentication failures
new_report	New DMARC or TLS report received

Severity Levels

Severity	Description
info	Informational, no action required
warning	Attention recommended
critical	Immediate action required

Example Request

curl -X GET "https://app.mailshield.app/api/v1/alerts?severity=critical&unreadOnly=true" \
  -H "Authorization: Bearer your_api_token"

Example: Filter by Domain

curl -X GET "https://app.mailshield.app/api/v1/alerts?domainId=a1b2c3d4-5678-90ab-cdef-1234567890ab" \
  -H "Authorization: Bearer your_api_token"

Error Responses

Status	Code	Description
401	unauthorized	Missing or invalid API token
404	not_found	Domain not found (when filtering by domainId)
429	rate_limited	Too many requests