Create alert

POST https://datafa.st/api/v1/admin/websites/{websiteId}/alerts

Create an email alert that fires when a visitor completes a goal. The email goes to the website owner's address unless you customize the template.

Goal names are saved lowercase and trimmed.

Related: Alerts announcement · Custom goals

Request

Path parameters

websiteId

string

Website ObjectId. From List websites (_id field). Example: 665f0b3c4d2e1a0012345678.

Body parameters

name

string

required

Alert label in the dashboard. Example: "New sale". Max 100 chars.

trigger.goalName

string

required

Goal that fires the alert. Example: "purchase". Lowercased when saved. Pick from List tracked goals.

template.message

string

required

Plain-text email body. Min 10, max 2000 characters. Example: "Someone just signed up on your site."

template.subject

string

Optional custom subject. Example: "New signup on example.com". Defaults to a standard alert subject when omitted.

isEnabled

boolean

true (default) sends emails; false creates a disabled alert.

Example request body

{
  "name": "New signup alert",
  "trigger": { "goalName": "signup" },
  "template": {
    "subject": "New signup!",
    "message": "A visitor just completed the signup goal."
  },
  "isEnabled": true
}

Response

Returns a JSON object with status: "success" and endpoint-specific fields in data.

Response fields

data[].id

string

Alert ObjectId.

data[].websiteId

string

Website ObjectId used by account tokens to choose which website to query or manage.

data[].name

string

Human-readable name for the resource or event. The exact meaning depends on the endpoint.

data[].trigger.type

string

Trigger type. Currently goal.

data[].trigger.goalName

string

Goal watched by the alert.

data[].destination.type

string

Destination type. Currently email.

data[].template.subject

string (optional)

Custom subject when configured; omitted otherwise.

data[].template.message

string

Human-readable confirmation or status message for the operation.

data[].isEnabled

boolean

Whether the alert is enabled.

data[].triggerCount

number

All-time successful trigger count.

data[].monthlyCount

number

Current billing-cycle trigger count.

data[].monthlyCountResetAt

string

Timestamp used to reset the monthly counter.

data[].dailyCount

number

Current UTC-day trigger count.

data[].dailyCountResetAt

string

Timestamp used to reset the daily counter.

data[].lastTriggeredAt

string|null (optional)

Latest successful trigger timestamp, when available; omitted before the first trigger.

data[].lastError

string|null (optional)

Latest delivery error, when available; omitted before an error is recorded.

data[].recentLogs

object[]

Recent trigger logs.

data[].createdAt

string

Creation timestamp.

data[].updatedAt

string

Last update timestamp.

Authentication

Use a dft_ account token with alerts:write.

A df_ website API key for the same website can also call this route when the path websiteId matches the key's website. Write access with a df_ key is capped at member level — owner-only actions such as team management require a dft_ token and owner role.

Errors

400 — Invalid alert data (name 1–100 chars, message 10–2000 chars, invalid goal name) or alert limit reached (max 25 per website).

See API errors for the standard error envelope, auth failures, validation errors, permission errors, and rate limits.

✍️ Something missing? Suggest features.

🤖 AI agent or LLM? Read this page as markdown

curl -X POST "https://datafa.st/api/v1/admin/websites/{websiteId}/alerts" \ -H "Authorization: Bearer dft_xxx" \ -H "Content-Type: application/json" \ -d '{"name":"New signup","trigger":{"goalName":"signup"},"template":{"message":"A visitor signed up."},"isEnabled":true}'

{ "status": "success", "data": [{ "id": "665f0b3c4d2e1a0012345678", "websiteId": "665f0b3c4d2e1a0012345678", "name": "New signup", "trigger": { "type": "goal", "goalName": "signup" }, "destination": { "type": "email" }, "template": { "subject": "New signup", "message": "A visitor signed up." }, "isEnabled": true, "triggerCount": 18, "monthlyCount": 4, "monthlyCountResetAt": "2026-05-01T00:00:00.000Z", "dailyCount": 1, "dailyCountResetAt": "2026-05-21T00:00:00.000Z", "lastTriggeredAt": "2026-05-21T12:00:00.000Z", "recentLogs": [], "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-05-21T12:00:00.000Z" }] }