如何通过 API 发送电子邮件：PHP、Node、Python、Go

通过API发送电子邮件的方法

To send an email through the YourTrend API, make a POST request to https://yourtrend.online/api/v1/messages with an Authorization: Bearer YOUR_API_KEY header and a JSON body containing from, to, subject and html. The server responds 202 Accepted, queues the message and signs it with DKIM. Below are working examples in curl and four SDKs.

获取API密钥并验证您的域名

在面板的“API密钥”下创建一个密钥——每个密钥都有如messages:send等作用域。您只能从经过验证的域名上的地址发送邮件：添加域名，发布SPF、DKIM和DMARC，并等待verified状态。请参阅文档，并在可送达性实验室中免费检查域名。

快速入门：curl

curl -X POST https://yourtrend.online/api/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "noreply@yourdomain.com",
    "to": "user@example.com",
    "subject": "欢迎！",
    "html": "<h1>你好</h1><p>感谢您的注册。</p>",
    "stream": "transactional"
  }'

成功的响应是HTTP 202:

{
  "data": {
    "id": "9b1c7e2a-1f3d-4b8a-9c11-4a2f6e8d0c33",
    "status": "queued",
    "stream": "transactional",
    "from": "noreply@yourdomain.com",
    "to": "user@example.com",
    "subject": "欢迎！"
  }
}

PHP

从/sdk/yourtrend.php获取单文件SDK——没有依赖，仅需cURL扩展。

<?php
require 'yourtrend.php';

$yt  = new YourTrend('YOUR_API_KEY');
$res = $yt->sendEmail(
    'noreply@yourdomain.com',
    'user@example.com',
    '欢迎！',
    '<h1>你好</h1>'
);

if ($res['status'] === 202) {
    echo '已排队: ' . $res['data']['data']['id'];
} else {
    echo '错误: ' . ($res['data']['error']['message'] ?? '未知');
}

Node.js

/sdk/yourtrend.js SDK使用内置的fetch（Node 18+），无需外部包。

const YourTrend = require('./yourtrend');
const yt = new YourTrend('YOUR_API_KEY');

const { status, data } = await yt.sendEmail(
  'noreply@yourdomain.com',
  'user@example.com',
  '欢迎！',
  '<h1>你好</h1>'
);

if (status === 202) console.log('已排队:', data.data.id);
else console.error('错误:', data.error?.message);

Python

该/sdk/yourtrend.py SDK 是纯标准库 (urllib) — 无需安装。

from yourtrend import YourTrend

yt = YourTrend('YOUR_API_KEY')
res = yt.send_email(
    'noreply@yourdomain.com',
    'user@example.com',
    '欢迎！',
    '<h1>你好</h1>',
)

if res['status'] == 202:
    print('已排队:', res['data']['data']['id'])
else:
    print('错误:', res['data']['error']['message'])

去

package main

import (
    "fmt"
    "log"
    "yourtrend"
)

func main() {
    c := yourtrend.New("YOUR_API_KEY")
    resp, err := c.SendEmail(
        "noreply@yourdomain.com",
        "user@example.com",
        "欢迎！",
        "<h1>你好</h1>",
    )
    if err != nil {
        log.Fatal(err)
    }
    defer resp.Body.Close()
    fmt.Println("HTTP", resp.StatusCode) // 202 = 已接受
}

额外字段

请求体接受四个基本字段以外的更多内容：

• text — 一个纯文本替代（建议与html一起使用）。
• cc, bcc, reply_to — 地址数组或以逗号分隔的字符串。
• 流 — 事务性或批量：拆分流量可以保护您的IP声誉。
• 附件 — 一个包含{文件名，内容，内容类型}对象的数组，内容为base64编码。
• 模板ID + 变量 — 发送带有合并替换的存储模板。
• 发送时间 — 用于定时发送的ISO-8601时间戳。

幂等性和测试模式

添加一个Idempotency-Key: <uuid>头部 — 在重试相同请求时（例如，在超时后），YourTrend返回第一个响应，而不是发送重复请求。X-Test-Mode: true头部在不进行实际发送和不消耗配额的情况下运行请求 — 在CI中非常方便。

处理错误

每个API错误都在一个信封中到达：

{
  "error": {
    "code": "quota_exceeded",
    "message": "每日发送限制已达到。",
    "request_id": "0f9d…"
  }
}

检查HTTP状态，而不仅仅是主体。常见代码：401 — 密钥错误；422 — 验证错误（一个错误字段列出了每个字段的问题）；429 — 速率限制，重试时使用指数退避；402/quota_exceeded — 计划配额耗尽。对于批量作业，请使用POST /api/v1/messages/batch（最多1000条消息，返回一个每条消息状态的207响应）。

想要为您的堆栈添加一个包装器吗？YourTrend的PHP、Node、Python和Go SDK每个都是一个无依赖的文件 — 直接复制到您的项目中。完整的端点和字段列表在API文档中，分层定价在定价页面上。

检查状态和Webhook

一旦排队，您可以通过GET /api/v1/messages/{id}读取消息的状态 — 响应包含状态（排队、已发送、已送达、退回、投诉）以及打开和投诉计数。逐条轮询API是浪费，因此请为交付事件设置Webhook：YourTrend在交付、打开、点击、退回和投诉时向您的URL发送一个POST。每个调用在头部中进行HMAC签名 — 验证签名以拒绝伪造，并在几秒钟内回复2xx；如果失败，Webhook将以递增的退避重试（重试队列）。这就是构建强大故障处理的方法：硬退回的邮件进入抑制列表，投诉得到立即反应，而您的分析数据在没有手动轮询的情况下填充。事件类型和有效负载形状的完整列表在文档中，发送层级在定价页面上。