Route · Email API
邮件 API
通过单一 API 发送 OTP、密码重置、账户提醒、发票与生命周期消息。Sendarix 为规模化下的可预测行为而设计，而非脆弱集成。
# 通过 routing policy 发送关键邮件 curl -sS -X POST 'https://app.sendarix.com/v1/email/send' \ -H 'Content-Type: application/json' \ -H 'X-API-Key: YOUR_API_KEY' \ -H 'Idempotency-Key: otp_8842' \ -d '{"to":"user@acme.com","template":"password_reset","routing_policy":"transactional-critical"}'
const sendarix = require("sendarix")(process.env.SENDARIX_KEY); await sendarix.email.send({ to: "user@acme.com", template: "password_reset", routingPolicy: "transactional-critical", idempotencyKey: "otp_8842" });
# Drop-in SMTP — 保留集成并获得 control plane host: smtp.sendarix.com port: 587 (STARTTLS) username: "your_sending_key" header: X-Sendarix-Policy: transactional-critical
稳定的接口契约
适合快速交付团队的实用 API
在一个一致的管道中认证请求、提交消息并追踪结果。每次发送均可通过日志、事件与 Webhooks 观察。
代表性产品 UI — 示例数据，并非实时客户指标。
您将获得
API 刻意保持直白：创建并发送消息、检查结果并自动化响应。帮助产品团队在不影响可靠性的前提下更快迭代。
快速 REST 集成
清晰的请求/响应模式，适合现代后端服务与内部工具的可预测行为。
消息生命周期追踪
追踪已接受、已投递、已退信与投诉状态，以便产品实时响应。
运营可见性
可搜索的日志与事件流在用户报告投递问题时缩短排障时间。
扩展无需重构
从早期工作负载到高流量流程，在流量增长时保持同一 API 契约。
模板数据注入
干净地传递动态变量，使事务性模板在各产品间保持一致。
幂等发送模式
在重试场景下通过确定性请求处理策略避免重复发送。
典型 API 流程
您的团队可一次性实现并在所有事务场景中复用的简单模式。
1. 提交请求
您的服务发布包含收件人、模板数据与元数据的消息负载。
2. 校验与入队
在投递阶段前进行输入检查、抑制逻辑与排队。
3. 投递
消息经可控发送行为路由至目标服务商。
4. 消费事件
使用 Webhooks 与日志更新产品状态并触发下游自动化。
常见问题
可以同时使用 API 与 SMTP 吗？
可以。许多团队在应用工作流中使用 API，在迁移期间对旧系统使用 SMTP。
每条消息都能获得事件数据吗？
可以。投递、退信与投诉事件可用于运营与产品工作流。
适合高流量吗？
适合。同一 API 模型适用于低流量上线阶段到持续高流量发送。
通过 API 发送需要 SPF、DKIM 与 DMARC 吗？
强烈建议认证您的发送域名。这有助于收件方评估您的邮件，也是生产流量的基线期望。
API 密钥与权限如何工作？
可为不同环境或服务签发密钥并限制各密钥权限，使预发、CI 与生产相互隔离。
若集成发送无效或重复请求会怎样？
API 对错误负载返回清晰的校验错误。重试时请在应用层使用稳定标识符，以免意外重复发送面向用户的邮件。
能否将 API 调用与下游投递关联？
可以。消息标识符与事件时间线可将特定 API 提交与已接受、已投递、已退信或延迟结果关联。
邮件 API 适合密码重置与 OTP 吗？
适合。这些是典型事务场景：低延迟期望、高可见性需求，并与认证或风控系统紧密耦合。
API 流量应仅使用 HTTPS 吗？
是。TLS 保护传输中的凭据与消息元数据。请将 API 端点视为其他生产级涉密表面。
What is the request rate limit on the Email API?
Rate limits vary by plan. Standard plans allow 1,000 requests/minute; enterprise plans support higher throughput. Rate limit headers are included in every response (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset). Exceeding the limit returns 429 Too Many Requests.
How do we handle API failures gracefully in our application?
Implement exponential backoff with jitter for retries. Treat 429 as a signal to slow down, 5xx as transient errors to retry, and 4xx (except 429) as permanent failures that should not retry. Store the message_id from successful submissions to correlate with downstream webhook events.
What is the maximum message size via API?
Messages up to 50MB total payload are accepted. For files larger than 25MB, Sendarix recommends hosting files externally and including a signed download link in the email body rather than attaching directly. Some mail servers reject messages exceeding 25MB.
Can we schedule email delivery for a future time?
Yes. Pass a scheduled_time parameter (ISO 8601 UTC timestamp) in your API request. Messages are queued and delivered at the specified time. Scheduled messages can be cancelled before delivery by calling the message cancel endpoint with the message_id.
How do we handle unsubscribe programmatically via the API?
The API provides /unsubscribes endpoints for managing suppression records. When a user unsubscribes, add them via the API to prevent future sends to that address. This integrates with the email webhooks unsubscribe event for automatic suppression list updates.
What response codes should our retry logic handle?
Handle these specifically: 200 OK (success, no retry), 400 Bad Request (invalid payload, fix before retry), 401 Unauthorized (invalid API key, do not retry), 422 Unprocessable Entity (validation error, fix payload), 429 Too Many Requests (rate limited, retry after X-RateLimit-Reset), 500 Internal Server Error (transient, retry with backoff).
相关产品
