获取 AcelleMail — $80

REST API · v1

一个 Token。每一个端点。

面向营销活动、名单、订阅者、自动化、发送服务器与客户计费的,简洁、资源化的 HTTP API。用一个 token 鉴权、查询 JSON、几分钟即可上线。插件调用的 API 与外部客户端调用的 API 完全相同 — 不存在二等公民端点。

4 步快速上手 ↓ 端点目录

您能构建什么

SaaS 前端 移动应用 CRM 同步 自动化触发器 分销商仪表盘
REQUEST POST /api/v1/campaigns HEADERS Authorization: Bearer ACELLE_TOKEN Content-Type: application/json BODY { "list_uid": "a3b9..." "name": "Welcome" "subject": "Hi friend" "from_name": "Acme" "from_email": "hi@..." "track_open": true "html": "<h1>…" } HTTPS your.acelle.com RESPONSE 200 OK { "campaign": { "uid": "abc123" "name": "Welcome" "subject": "Hi friend" "status": "ready" "track_open": true "created_at": "2026-05-06T…" "links": { "self": "/api/v1…" } } }

为何选这套 API

无惊喜。无二等公民端点。
您的插件用的就是同一套 API。

Token 鉴权

每一次请求都携带一个 bearer token。从 Profile → API token 按用户生成。通过 Authorization: Bearer 头或 ?api_token= 查询参数传递。可随时吊销与轮换。

资源化

每一个概念都是带可预测动词的资源。GET /lists 返回集合,POST /lists 创建一个,PATCH /lists/:uid 更新,DELETE /lists/:uid 删除。子资源自然嵌套:/lists/:uid/subscribers。

与插件相同

不存在内部与外部之分。AcelleMail 自身 UI 调用的端点、您插件扩展的端点、您外部客户端读取的端点 — 完全相同。查看插件 SDK →

自托管端点

基础 URL 是您自有的服务器 — https://your-acelle.example.com/api/v1/。无厂商代理、无共享速率上限、无按请求计费。吞吐由您硬件决定。

快速上手

四步从零到首次响应。

每份 AcelleMail 部署在 /api/v1/ 托管自己的 API。请把 your-acelle.example.com 替换为您部署的主机名。

STEP 1

生成 token

登录您的 AcelleMail 部署。打开个人资料菜单并点击 API token。复制值 — 它按用户唯一,与该用户的权限绑定。

# In your shell:
$ export ACELLE_TOKEN=paste-your-token-here
$ export ACELLE_BASE=https://your-acelle.example.com
STEP 2

验证 token

调用 /me。token 有效则返回您的用户记录。无效则返回 401 — 检查 token 与基础 URL。

$ curl $ACELLE_BASE/api/v1/me \
    -H "Authorization: Bearer $ACELLE_TOKEN"

{ "id": 1, "email": "you@…", "uid": "…" }
STEP 3

创建名单

资源通过 POST 创建。邮件名单的必填正文字段是 name、from_email、from_name、subject,加上联系人区块。

$ curl -X POST $ACELLE_BASE/api/v1/lists \
    -H "Authorization: Bearer $ACELLE_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "name":       "Newsletter",
      "from_name":  "Acme",
      "from_email": "hi@acme.com",
      "subject":    "Welcome"
    }'
STEP 4

添加订阅者

使用第 3 步获得的名单 UID。自定义字段以大写参数 (FIRST_NAME、LAST_NAME、…) 传递,匹配您名单的字段配置。

$ curl -X POST $ACELLE_BASE/api/v1/subscribers \
    -H "Authorization: Bearer $ACELLE_TOKEN" \
    -d list_uid=$LIST_UID \
    -d EMAIL=alice@example.com \
    -d FIRST_NAME=Alice \
    -d tag=newsletter,beta

资源

八种资源。40+ 端点。您预期的每一个动词。

下方所有端点都命名于 /api/v1/ 下,除非另行标注,均需 auth:api token 鉴权。生命周期动作 (run、pause、resume) 以 POST 子路由暴露。日志下载流式输出底层 CSV。

鉴权

所有已鉴权的端点都通过 Authorization: Bearer 头 (推荐) 或 ?api_token= 查询参数 (遗留) 接受 token。从程序化客户端用 POST /user/login 以邮箱/密码换取新 token。

POST/user/login用邮箱 + 密码换取 API token。公开端点。
GET/me返回已鉴权用户的记录。用此验证 token。
POST/login-token生成一次性登录 URL,用户点击即可进入已登录状态。

名单

邮件名单是订阅者的主要容器。每个名单附默认发件人身份、自定义字段,以及双重确认/欢迎邮件设置。自定义字段用 add-field 子路由添加。

GET/liststoken 所属用户拥有的名单分页索引。
POST/lists创建新名单。必填:name、from_email、from_name、subject + 联系人区块。
GET/lists/:uid获取单个名单及其字段与统计。
PATCH/lists/:uid更新名单元数据、发件人身份或确认设置。
POST/lists/:uid/add-field添加自定义字段。类型为 text、number 或 datetime。
DELETE/lists/:uid永久删除一份名单及其所有订阅者。

订阅者

订阅者归属于一份名单,携带自定义字段值、标签与打开/点击历史。状态为 subscribed、unsubscribed 或 unconfirmed 之一。标签操作是累加且幂等的。

GET/subscribers?list_uid=…分页索引。可用 open=yes|no、click=yes|no 筛选。
POST/subscribers创建。必填:list_uid、EMAIL。自定义字段以大写参数传递。
GET/subscribers/:id按 id 或 email 获取单个订阅者。
GET/subscribers/email/:email找出每份带该 email 订阅者的名单。
PATCH/subscribers/:id更新字段、标签或状态。
POST/subscribers/:id/add-tag添加逗号分隔的标签。
POST/subscribers/:id/remove-tag移除逗号分隔的标签。
PATCH/lists/:list_uid/subscribers/:id/subscribe标记为 subscribed。
PATCH/lists/:list_uid/subscribers/:id/unsubscribe标记为 unsubscribed。
PATCH/lists/:list_uid/subscribers/email/:email/unsubscribe当您没有 id 时按 email 退订。
DELETE/subscribers/:id从名单中硬删除。

营销活动

营销活动是发送的单位。创建一次,附带 HTML 内容 + 追踪标志,在 run / pause / resume 之间切换,然后以 CSV 形式下载追踪、打开、点击、退信、反馈与退订日志。

GET/campaigns分页索引。传 per_page、page。
POST/campaigns创建。必填:list_uid、name、subject、from_*、html。
GET/campaigns/:uid获取单个营销活动与统计。
PATCH/campaigns/:uid更新内容、主题或追踪标志。
POST/campaigns/:uid/run把营销活动排入投递队列。
POST/campaigns/:uid/pause暂停进行中的营销活动。
POST/campaigns/:uid/resume恢复已暂停的营销活动。
GET/campaigns/:uid/tracking-log/download流式输出追踪 CSV。
GET/campaigns/:uid/{open,click,bounce,feedback,unsubscribe}-log/download流式输出按事件的 CSV (每种事件类型一条路由)。
DELETE/campaigns/:uid删除营销活动 (仅当未进行中时)。

自动化

自动化是触发器、条件与动作的可视化流程。API 暴露读视图,加两种从外部系统触发流程的方式:execute 运行整个自动化,或 api/call 在流程中触发一个"API call"节点。

GET/automationstoken 所属用户拥有的自动化索引。
POST/automations/:uid/execute为订阅者触发自动化。事务性流程很有用。
POST/automations/:uid/api/call在流程中以自定义载荷触发一个"API call"触发器节点。

发送服务器

发送服务器是可配置的传输 (SMTP、Amazon SES、SendGrid、Mailgun、Postmark、插件提供的自定义驱动)。当开通新租户或轮换凭据时以编程方式管理。

GET/sending_servers已配置发送服务器的索引。
POST/sending_servers创建新发送服务器。驱动专属配置在 settings 下。
GET/sending_servers/:uid获取单个发送服务器。
PATCH/sending_servers/:uid更新设置或轮换凭据。
DELETE/sending_servers/:uid移除发送服务器 (引用它的营销活动必须先重新路由)。

新增一种传输 (Postal MTA、自定义 HTTP API、…) 是一次 REGISTRY hook — 以插件形式交付,而不是修补核心。

客户 管理员

客户端点限定到管理员 token。用它们开通租户账户、管理订阅、切换套餐,或为支持/模拟登录生成一次性登录 URL。

GET/customers所有客户的分页索引。
POST/customers创建新客户 + 用户账户。
GET/customers/by-email/:email按 email 查找客户。
PATCH/customers/:uid更新客户档案/联系人/配额。
PATCH/customers/:uid/{enable,disable}暂停或重新激活访问而不删除数据。
POST/customers/:uid/change-plan/:plan_uid将客户切到不同套餐 (扣费、按比例、续订)。
POST/customers/:uid/assign-plan/:plan_uid分配套餐而不走计费流程 (管理员覆盖)。
POST/customers/:uid/subscription/update更新活跃订阅的参数。
POST/login-token为目标客户生成一次性登录 URL。

订阅 管理员

订阅把客户与套餐 + 计费节奏绑定。当与外部计费系统集成或审计经常性收入时使用这些端点。

GET/subscriptions所有活跃订阅的索引。
POST/subscriptions创建订阅记录 (通常由您的网关 webhook 驱动)。
GET/subscriptions/:uid获取单个订阅及其续订历史。
PATCH/subscriptions/:uid调整配额、节奏或结束日期。

文件

上传图片与其他资源以用于营销活动内容。端点接受 multipart/form-data,返回您可在 HTML 正文中引用的公开 URL。

POST/file/upload上传文件。返回 { "url": "..." }。

插件与升级 管理员

以编程方式从下载 URL 安装插件、以两步请求流程运行远程核心升级 (以便第 2 步落在新的 PHP 工作进程上),或刷新授权。对管理众多 AcelleMail 租户的舰队运营者很有用。

POST/plugins/install从下载 URL 安装插件。
POST/upgrade/run开始远程核心升级 (下载 + 解压)。
POST/upgrade/run-file应用单一迁移步骤。
POST/upgrade/finalize完成升级。必须作为 run 之后的新请求调用。
POST/license/refresh刷新 CodeCanyon 授权信息 (镜像 Admin → License)。

WEBHOOK

把事件推送出去,而不是轮询。

AcelleMail 交付两种 webhook 接入面。生命周期 webhook在客户 + 订阅 + 自动化转换时触发,全局配置。按收件人追踪 ping在打开/点击/退订时触发,按营销活动配置。两者都在失败时以指数退避重试。

生命周期 webhook

客户 + 订阅转换

在 Admin → Settings → Webhooks 一次性配置。每个 webhook 是名称 + 事件 + 出站 HTTP 配置 (URL、方法、头、正文模板)。核心交付六种事件:

new_customer — 参数: customer_id
new_subscription — customer_id, plan_id
change_plan — customer_id, old_plan_id, new_plan_id
cancel_subscription — customer_id, plan_id
terminate_subscription — customer_id, plan_id
automation_webhook — automation_id (从 API call 节点触发)

重试策略按 webhook:可配置 retry_times (默认 2) 与 retry_after_seconds (默认 900)。失败投递被记录、重试,并在管理员 webhook 日志中呈现。

插件可以通过 EVENT hook 模式注册额外事件 — 例如 acelle/ai 从其自定义监听器触发 ai_task_completed。

按收件人追踪

打开、点击、退订

按营销活动或按邮件模板在 Tracking → Webhooks 下配置。三种事件类型在收件人与消息互动时触发:

open — 收件人打开了邮件 (追踪像素)
click — 收件人点击了已追踪链接
unsubscribe — 收件人点击了退订链接

每次 ping 携带营销活动 uid、订阅者 email,以及点击 URL (针对 click 事件)。按需配置多条追踪 webhook — 适合并行镜像到分析 + CRM + 数据仓库。

发送服务器级事件 (退信、投诉、投递) 通过 App\SendingServers\Webhooks\* 内部监听器栈流转 — 在营销活动日志端点中呈现,而非作为出站 webhook。下载日志 CSV →

示例:new_subscription 载荷

POST /your-webhook-url
Content-Type: application/json
X-AcelleMail-Event: new_subscription
X-AcelleMail-Signature: sha256=…

{
  "event":       "new_subscription",
  "customer_id": 1234,
  "plan_id":     "extended-monthly",
  "fired_at":    "2026-05-06T12:34:56Z"
}

示例:click 追踪载荷

POST /your-webhook-url
Content-Type: application/json
X-AcelleMail-Event: click

{
  "event":         "click",
  "campaign_uid":  "abc123",
  "subscriber":    "alice@example.com",
  "url":           "https://acme.com/promo",
  "clicked_at":    "2026-05-06T12:34:56Z"
}

响应与错误

可预测的 JSON。约定俗成的状态码。

每一次成功响应都是 JSON。每一次失败响应也是 JSON,带顶级 message 与用于校验失败的 errors map。状态码遵循 REST 约定 — 您可以仅按状态码分支客户端。

状态码 何时会看到
200 OK读或更新成功。
201 Created创建成功。
401 Unauthorizedtoken 缺失或无效。
403 Forbiddentoken 有效,但该资源不是您的/非管理员。
404 Not FoundUID 不存在。
422 Unprocessable校验错误。请检查响应正文中的 errors map。
500 Server服务端缺陷。请查看 storage/logs/laravel.log。

校验错误 (422)

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "message": "The given data was invalid.",
  "errors": {
    "from_email": [
      "The from_email field is required."
    ],
    "subject": [
      "The subject must be at most 998 characters."
    ]
  }
}

鉴权失败 (401)

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{ "message": "Unauthenticated." }

分页

索引端点接受 per_page (按资源默认 10–25) 与 page。响应包含标准 Laravel 分页器形状:data[]、links、meta.current_page、meta.total。

速率限制

速率限制由您决定 — 通过 Laravel 部署中的 RouteServiceProvider 设置。原版构建不附 API 节流,因为您调用的是自己的服务器。需要时加 throttle:60,1。

版本化

当前大版本为 v1。新端点可自由新增;现有端点的破坏性变更将作为 v2 与 v1 并行发布。把您的客户端锁定到 /api/v1/,即稳定。

客户端

任意 HTTP 客户端。无专有 SDK。

没有 AcelleMail SDK 要安装。这套 API 通过 HTTP 说 JSON — 用您技术栈已有的任意客户端。实操中最常见的三种:

curl · 单行命令

curl $ACELLE_BASE/api/v1/lists \
  -H "Authorization: Bearer $ACELLE_TOKEN" \
  | jq '.data[].name'

Laravel HTTP 客户端

$resp = Http::withToken($token)
    ->baseUrl($base.'/api/v1')
    ->post('/subscribers', [
        'list_uid' => $listUid,
        'EMAIL'    => $email,
    ]);

return $resp->json();

浏览器 / Node fetch

const r = await fetch(
  `${base}/api/v1/campaigns/${uid}/run`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
    },
  }
);
const data = await r.json();

在做开源 SDK？给我们发邮件 — 我们会从本页链向它。

规范参考

完整、可执行的 API 参考。

每一个参数。每一种返回形状。每一个可工作的 curl 示例。托管在规范的演示部署上 — 您部署运行的是同一份代码。

api.acellemail.com

调用时请把 api.acellemail.com 替换为您自己的部署主机名。

资源与社区

用这套 API 构建、以插件形式交付,遇阻时联系我们。

面向开发者

插件 SDK、Hook 系统、5 分钟 Hello World 插件,以及 14 个带真实生产案例的扩展接入面。

/for/developers →

完整 API 参考

面向每一个端点的实时可执行参考 — 参数、返回、可工作的 curl 示例。

api.acellemail.com →

知识库

配置、送达率、发送服务器配置、故障排除、插件指南、计费。

acellemail.com/kb →

遇阻？给我们发邮件

端点契约、webhook 载荷或鉴权问题。典型 24 小时内回复。

support{{ landing_brand('domain') }} →

开始构建

运行 AcelleMail。获取 token。发起调用。

一次性授权。完整源代码。自托管端点。API 已含 — 无附加费、无速率套餐。

获取 AcelleMail — $80 插件 SDK →

在您自己的服务器上,按您自己的方式运营邮件营销

加入数千家企业的行列,以完整源代码、零订阅费用、无限发送量掌控自己的邮件营销。$80 一次性授权,终身更新。

获取 AcelleMail — $80 一次性付款

Get the AcelleMail newsletter

Monthly issue with new releases, deliverability tips, and self-hosting playbooks. No spam.