Overview

Stay informed about schema issues without manual checking. Email alerts notify users when automated re-scans detect new validation errors, significant score drops, or schema changes.

How It Works

1. User configures alert preferences (types, frequency, recipients)
2. After each re-scan, results are checked against alert criteria
3. If criteria are met, an email notification is sent
4. Alerts are logged in the dashboard for review
5. Alerts can be marked as read/acknowledged

Tier Availability

| Tier | Available | Alert Types |
|——|———–|————-|
| Free | No | — |
| Pro | Yes | Errors, score drops |
| Agency | Yes | + Schema changes, monitoring alerts |
| Enterprise | Yes | + Custom rules |

Related Features

– Automated Re-scans: Triggers that generate alerts
– Schema Change Detection: Change-based alerts (Agency+)
– Custom Alert Rules: Define custom triggers (Enterprise)

Quick Start: Enable Email Alerts

Step 1: Configure alert settings

curl -X POST https://api.validgraph.io/wp-json/validgraph/v1/alerts/settings 
  -H "Authorization: Bearer YOUR_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "enabled": true,
    "recipients": ["[email protected]"],
    "alert_types": {
      "validation_errors": true,
      "score_drop": {"enabled": true, "threshold": 5},
      "schema_changes": true
    },
    "frequency": "immediate"
  }'

Step 2: Alerts send automatically when criteria are met during rescans

Step 3: Review alerts in dashboard — Mark as read/acknowledged

Example workflow:
Configure alerts for product pages. When daily rescan detects score drop >5 points, email notification sent within 5 minutes. Example: “Product page score: 85 → 78 (-7 points). New error: Missing image property.”

Technical Details

Alert Settings Endpoint

Get current alert settings:

GET /wp-json/validgraph/v1/alerts/settings

Response:

{
  "success": true,
  "data": {
    "alerts_enabled": true,
    "recipients": ["[email protected]", "[email protected]"],
    "alert_types": {
      "validation_errors": {
        "enabled": true,
        "error_types": ["all"]
      },
      "score_drop": {
        "enabled": true,
        "threshold": 5,
        "min_score": 0
      },
      "schema_changes": {
        "enabled": true,
        "severity_filter": "high"
      },
      "monitoring_failure": {
        "enabled": true
      }
    },
    "notification_frequency": "immediate",
    "digest_time": null
  }
}

Update alert settings:

POST /wp-json/validgraph/v1/alerts/settings
{
  "recipients": ["[email protected]"],
  "alert_types": {
    "validation_errors": true,
    "score_drop": {"threshold": 10},
    "schema_changes": {"severity_filter": "high"}
  }
}

Alert Types by Tier

Pro tier:
– Validation errors detected (new errors in rescan)
– Score drops (threshold configurable)
– Monitoring failures (URL unreachable)

Agency tier (includes Pro + ):
– Schema changes (property/type added/removed/modified)
– High-severity changes only

Enterprise tier (includes Agency + ):
– Custom alert rules (defined per account)
– Multiple notification channels (email, webhook)

Alert List Endpoint

Get recent alerts:

GET /wp-json/validgraph/v1/alerts

Response:

{
  "success": true,
  "data": {
    "total": 8,
    "unread": 3,
    "alerts": [
      {
        "alert_id": "alert_001",
        "timestamp": "2024-03-21T06:15:00Z",
        "type": "score_drop",
        "severity": "high",
        "monitoring_id": "mon_abc123",
        "url": "https://example.com/product",
        "previous_score": 85,
        "current_score": 78,
        "score_change": -7,
        "trigger_reason": "Score dropped 7 points (threshold: 5)",
        "new_errors": [
          {
            "type": "Product",
            "property": "image",
            "message": "Recommended property missing"
          }
        ],
        "action_url": "/alerts/alert_001",
        "read": false,
        "acknowledged": false
      },
      {
        "alert_id": "alert_002",
        "timestamp": "2024-03-21T06:10:00Z",
        "type": "validation_error",
        "severity": "medium",
        "monitoring_id": "mon_def456",
        "url": "https://example.com/article",
        "error_count": 1,
        "new_errors": [
          {
            "type": "Article",
            "property": "datePublished",
            "message": "Invalid date format"
          }
        ],
        "read": true,
        "acknowledged": true
      },
      {
        "alert_id": "alert_003",
        "timestamp": "2024-03-20T23:45:00Z",
        "type": "monitoring_failure",
        "severity": "high",
        "monitoring_id": "mon_ghi789",
        "url": "https://example.com/old-page",
        "failure_reason": "HTTP 404 - Page not found",
        "retry_info": {
          "automatic_retry": true,
          "retry_at": "2024-03-21T00:45:00Z"
        },
        "read": false
      }
    ]
  }
}

Alert Actions

Mark single alert as read:

PUT /wp-json/validgraph/v1/alerts/alert_001/read

Mark all alerts as read:

PUT /wp-json/validgraph/v1/alerts/read-all

Response:

{
  "success": true,
  "data": {
    "alerts_marked_read": 3
  }
}

Email Alert Template Example

Subject: “Schema validation alert: Product page score dropped (85 → 78)”

Body:

ValidGraph Alert: Score Drop Detected

URL: https://example.com/product
Monitoring ID: mon_abc123
Alert Time: March 21, 2024 6:15 AM UTC

Previous Score: 85/100
Current Score: 78/100
Change: -7 points

Trigger Reason: Score exceeded drop threshold (configured: 5 points)

New Issues Detected:
• Product (Recommended): image property is missing
  - Adding an image significantly improves CTR in search results

Recent Changes:
- Previous scan: 2024-03-14 (0 errors, 2 warnings)
- Current scan: 2024-03-21 (1 error, 3 warnings)

Recommendation:
Add the image property to improve score and rich snippet eligibility.

View Full Report: https://validgraph.io/validations/val_scan_123
Manage Alerts: https://validgraph.io/settings/alerts

Severity Levels for Alerts

| Severity | Triggers |
|———-|———-|
| Critical | URL unreachable (404, 500), Required property removed, Type changed |
| High | Score drop >10 points, New validation error, Schema type lost |
| Medium | Score drop 5-10 points, Recommended property missing, Minor changes |
| Low | Optional property change, Score drop <5 points, Minor warnings |

Notification Frequency Options

– Immediate: Alert fires as soon as rescan completes
– Hourly digest: Alerts batched and sent hourly
– Daily digest: Alerts batched and sent daily at 8 AM
– Weekly digest: Alerts batched and sent weekly (Monday 9 AM)

Unsubscribe/Manage Preferences

Each email includes footer with:
– Unsubscribe link
– Manage alert settings link
– View full report link

---
Manage your ValidGraph alerts: https://validgraph.io/alerts/settings
View this alert online: https://validgraph.io/alerts/alert_001
Unsubscribe from this alert type: https://validgraph.io/alerts/unsubscribe?token=xyz

References

– Email Standards (RFC 5321): https://tools.ietf.org/html/rfc5321
– Email Headers (RFC 5322): https://tools.ietf.org/html/rfc5322
– DKIM Signing: https://tools.ietf.org/html/rfc6376
– Webhook Security: https://tools.ietf.org/html/rfc6455
– Alert Pattern Best Practices: https://www.alertmanager.io/