Alerts

Retrieve alerts for your organization's monitored domains.

List Alerts

GET /api/v1/alerts

Returns a paginated list of alerts for your organization, newest first.

Query Parameters

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

page and limit must be whole numbers, and severity one of the three values; anything else returns 400.

Response

{
  "data": [
    {
      "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "domainId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "domainName": "example.com",
      "type": "score_change",
      "severity": "warning",
      "title": "Score dropped for example.com",
      "message": "The security score for example.com dropped from 85 (Good) to 77 (Fair).",
      "metadata": {
        "previousScore": 85,
        "currentScore": 77,
        "scoreDiff": -8,
        "previousRating": "Good",
        "currentRating": "Fair",
        "scoringVersion": 1,
        "changes": [
          {
            "component": "DMARC",
            "previousScore": 25,
            "currentScore": 17,
            "diff": -8,
            "description": "DMARC: 25 → 17 points"
          }
        ]
      },
      "read": false,
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "hasMore": false
    }
  }
}

Alert Types

Type	Description
score_change	The domain's security score went up or down. metadata has previousScore, currentScore, scoreDiff and the per-component changes
dns_change	A DNS record changed, for example a weaker DMARC policy or a removed record
report_failure	DMARC reports show messages failing authentication
tls_failure	TLS-RPT reports show failed TLS connections, or a problem with the mail servers' TLS setup
cert_expiry	A certificate is expiring soon or has expired

The type field can also hold score_threshold and new_report. They're reserved, and no alerts of these types are sent today.

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
400	validation_error	Invalid page, limit or severity
401	unauthorized	Missing or invalid API token
404	not_found	Domain not found (when filtering by domainId)
429	rate_limited	Too many requests