---
title: "Create a standing listing alert (email, human-confirmed)"
method: POST
path: "/api/v1/alerts"
---

# Create a standing listing alert (email, human-confirmed)

`POST /api/v1/alerts`

## Request

- Base URL: `https://macfax.com`
- URL: `https://macfax.com/api/v1/alerts`
- Auth: one of:
  - none
  - HTTP bearer
  - API key in header `X-Api-Key`
  - API key in query parameter `api_key`

Watch the market for a configuration: a daily email when new matching listings appear. CONSENT CONTRACT: create an alert only for a user who explicitly asked for this alert on this email address. The first alert for a new email is created as pending_confirm and activates only when the email's owner clicks the confirmation link — nothing sends before that, and unconfirmed alerts don't exist for any other purpose. Every alert email carries manage + unsubscribe links. Per-email creation is capped at 5/day. Rate limits: 5/min and 20/day per anonymous IP; 10/min and 40/day with a free key.

## Request body

- object
  - `email` string, email, required
  - `config` string, required: config_key_l0 or _l1
  - `ram_gb` integer
  - `storage_gb` integer
  - `max_price_usd` integer
  - `min_tier` 'listed' | 'free' | 'premium'
  - `under_typical` boolean: Only listings under the config's typical asking range (p25 gate).

## Response `201`

Created — status is active or pending_confirm.

## Other responses

- `400`: Invalid email or config.
- `429`: Rate limited (per-caller or per-email).

---

[API](https://skmtc.dev/macfax/apis/macfax-api.md) · [All operations](https://skmtc.dev/macfax/apis/macfax-api/llms.txt) · [OpenAPI document](https://skmtc.dev/macfax/apis/macfax-api/revisions/ce892dbbd7d5?raw)