Alerts tools

The alerts feature includes read and write tools for goal-triggered email alerts. Alerts can include a name, enabled state, goal-event triggers, recipient email, subject template, and markdown body template.

Supported access levels

Role requirements and site scoping

Alert tools require alerts:read or alerts:write for the selected site. Supply siteId for multi-site connections.

Users and AI clients should call faurya_get_alert_template_reference to retrieve the current supported template variables rather than hard-coding a variable list.

Tool summary

Common errors

ALERTS_SCOPE_REQUIRED, INSUFFICIENT_SCOPE, SITE_SCOPE_REQUIRED, VALIDATION_ERROR, INVALID_FIELD, NOT_FOUND, and RATE_LIMITED.

faurya_get_alert_template_reference

What it does

Reads supported alert template variables, default subject/body, markdown support, and special table variables for a permitted Faurya site.

Permission required

Alerts: Read.

When to use it

Use before creating or editing alert templates.

Example prompt

Show the supported alert template variables.

Input

Example MCP input

{ "siteId": "site_example" }

Output

data contains template variables, default templates, markdown support, and table-variable guidance.

Example output

{
  "success": true,
  "requestId": "req_example",
  "data": {
    "markdownSupported": true,
    "defaultSubject": "Goal alert for {{site.name}}",
    "variables": [{ "name": "site.name", "description": "Site display name" }]
  },
  "meta": {
    "warnings": [],
    "pagination": { "nextCursor": null, "hasMore": false }
  }
}

Common errors

INSUFFICIENT_SCOPE, SITE_SCOPE_REQUIRED.

Notes

Do not manually invent the complete variable list. Retrieve the current reference with this tool.

faurya_list_alerts

What it does

Lists email alerts configured for a permitted Faurya site, including trigger goals, recipient, templates, enabled state, firing counters, and last-fired time where available.

Permission required

Alerts: Read.

When to use it

Use to audit configured alerts or find an alertId before updating or deleting.

Example prompt

List goal alerts for this site.

Input

Example MCP input

{ "siteId": "site_example" }

Output

data contains alert rows.

Example output

{
  "success": true,
  "requestId": "req_example",
  "data": {
    "alerts": [
      {
        "id": "alert_example",
        "alertName": "Signup alert",
        "goalEvents": ["signup"],
        "recipientEmail": "user@example.com",
        "enabled": true,
        "firingCount": 3,
        "lastFiredAt": "2026-07-18T10:00:00.000Z"
      }
    ]
  },
  "meta": {
    "warnings": [],
    "pagination": { "nextCursor": null, "hasMore": false }
  }
}

Common errors

INSUFFICIENT_SCOPE, SITE_SCOPE_REQUIRED.

Notes

Use placeholder emails in examples and prompts.

faurya_create_alert

What it does

Creates an email alert for one or more goal events on a permitted Faurya site using documented alert template variables.

Permission required

Alerts: Write.

When to use it

Use when a user asks to be notified by email when specific goals fire.

Example prompt

Create an enabled signup alert for user@example.com.

Input

Example MCP input

{
  "siteId": "site_example",
  "enabled": true,
  "alertName": "Signup alert",
  "goalEvents": ["signup"],
  "recipientEmail": "user@example.com",
  "emailSubject": "New signup on {{site.name}}",
  "emailBody": "A signup goal fired."
}

Output

data contains the created alert.

Example output

{
  "success": true,
  "requestId": "req_example",
  "data": {
    "id": "alert_example",
    "alertName": "Signup alert",
    "enabled": true,
    "goalEvents": ["signup"],
    "recipientEmail": "user@example.com"
  },
  "meta": {
    "warnings": [],
    "pagination": { "nextCursor": null, "hasMore": false }
  }
}

Common errors

VALIDATION_ERROR, INSUFFICIENT_SCOPE, INVALID_FIELD.

Notes

This changes persistent alert configuration. Confirm recipient email and trigger goals before calling.

faurya_update_alert

What it does

Updates an existing email alert's enabled state, trigger goals, recipient, name, subject template, or body template.

Permission required

Alerts: Write.

When to use it

Use to pause alerts, change recipients, adjust trigger goals, or edit templates.

Example prompt

Disable alert_example.

Input

Example MCP input

{ "siteId": "site_example", "alertId": "alert_example", "enabled": false }

Output

data contains the updated alert.

Example output

{
  "success": true,
  "requestId": "req_example",
  "data": { "id": "alert_example", "enabled": false },
  "meta": {
    "warnings": [],
    "pagination": { "nextCursor": null, "hasMore": false }
  }
}

Common errors

NOT_FOUND, VALIDATION_ERROR, INSUFFICIENT_SCOPE.

Notes

Only supplied fields are changed. Confirm template changes before calling.

faurya_delete_alert

What it does

Deletes an existing email alert from a permitted Faurya site.

Permission required

Alerts: Write.

When to use it

Use only after clear confirmation that the alert should be removed.

Example prompt

Delete alert_example after I confirm.

Input

Example MCP input

{ "siteId": "site_example", "alertId": "alert_example" }

Output

data confirms deletion.

Example output

{
  "success": true,
  "requestId": "req_example",
  "data": { "deleted": true, "alertId": "alert_example" },
  "meta": {
    "warnings": [],
    "pagination": { "nextCursor": null, "hasMore": false }
  }
}

Common errors

NOT_FOUND, VALIDATION_ERROR, INSUFFICIENT_SCOPE.

Notes

Destructive: deletion removes the alert. Ask for confirmation first.

Example prompts

• “List all enabled signup alerts.”
• “Show the alert template variables.”
• “Create an alert for signup goals sent to user@example.com.”
• “Disable alert_example.”
• “Delete alert_example after I confirm.”

Related pages

• Overview
• Installation
• Analytics