---
title: "Newsletter & Email Subscriptions"
canonical_url: "https://ainode.run/docs/newsletter-subscriptions"
type: "doc"
locale: "en"
description: "Core API endpoints for email/webhook topic subscriptions, one-click unsubscribe, and admin broadcasts."
---

# Newsletter & Email Subscriptions
> Core API endpoints for email/webhook topic subscriptions, one-click unsubscribe, and admin broadcasts.

# Newsletter & Email Subscriptions API

APay provides a built-in, multi-topic email and webhook subscription engine (`newsletter_subscribers`) used across blogs, product updates, Hoxi solopreneur playbooks (`blog` / `hoxi_updates`), and TiboSay Codex reset alerts (`codex_resets`).

---

## Public Endpoints

### 1. Subscribe (`POST /api/newsletter/subscribe`)

Registers or reactivates an email address or HTTPS webhook URL for a given topic.

#### Request Body

```json
{
  "channel": "email",
  "email": "developer@example.com",
  "topic": "blog",
  "source": "hoxi_blog",
  "locale": "zh",
  "sendWelcome": true
}
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `channel` | `'email' | 'webhook'` | No | Defaults to `'email'` |
| `target` / `email` | `string` | Yes | Email address or HTTPS webhook URL |
| `topic` | `string` | No | Topic identifier (`general`, `blog`, `hoxi_updates`, `codex_resets`). Defaults to `'general'` |
| `source` | `string` | No | Attribution source (`web`, `hoxi_blog`, `codex`, etc.) |
| `locale` | `string` | No | Preferred language (`zh`, `en`) |
| `sendWelcome` | `boolean` | No | Whether to send a confirmation email upon new/reactivated subscription |

#### Response (200)

```json
{
  "ok": true,
  "code": 0,
  "isNew": true,
  "reactivated": false,
  "topic": "blog",
  "channel": "email",
  "message": "Subscribed! We will notify your inbox as soon as new updates drop."
}
```

---

### 2. Unsubscribe / Resubscribe (`GET` or `POST /api/newsletter/unsubscribe`)

Every broadcast email automatically includes a unique token link (`/api/newsletter/unsubscribe?token=`).

- **`GET /api/newsletter/unsubscribe?token=...`**: Marks the subscription as `unsubscribed` and renders a bilingual HTML confirmation page with a one-click **Resubscribe** button (`?token=...&action=resubscribe`). Pass `format=json` or `Accept: application/json` for a JSON response.
- **`POST /api/newsletter/unsubscribe`**: Accepts `{ "token": "...", "action": "unsubscribe" | "resubscribe" }`.

---

## Admin Endpoints

All admin endpoints require `settings:view` (for `GET`) or `settings:edit` (for `POST`).

### 1. List Subscribers (`GET /api/admin/email/subscribers`)

Query parameters: `page`, `pageSize`, `search`, `topic`, `status` (`active` | `unsubscribed` | `all`), `channel` (`email` | `webhook` | `all`).

### 2. Manage Subscriber (`POST /api/admin/email/subscribers`)

Supports `action: 'create' | 'toggle' | 'delete'`.

### 3. Broadcast Notification (`POST /api/admin/email/broadcast`)

Sends a bilingual HTML email and/or webhook broadcast to all active subscribers of a topic (or a single `targetEmail` for testing) via `deliverEmail()`.

```json
{
  "topic": "blog",
  "subjectZh": "🚀 新文章发布",
  "subjectEn": "🚀 New Article Published",
  "htmlZh": "

## 标题

正文内容...

"
}
```