快速开始

本指南带你从零开始，到从自己的域名发出一封真实邮件。

1. 创建 API 密钥

   打开控制台，进入 API 密钥，点击 创建 API 密钥。试用阶段请选择 full_access。请立即复制密钥：它以 sp_live_ 开头，只会显示一次。

   export SPACEPOST_API_KEY="sp_live_YOUR_API_KEY"

   警告

   请把密钥保存在服务器端，切勿放进浏览器或移动端代码。为每个服务创建一个 sending_access 密钥，这样可以单独吊销某一个而不影响其他服务。

2. 发送测试邮件

   无需域名即可立即发送，使用共享的测试发件人 onboarding@test.spacepost.dev。它只能投递到你团队成员的邮箱地址以及测试地址，例如 delivered@test.spacepost.dev。

   Node.js

   npm install @spacepost/node

   send.ts

   import { SpacePost } from "@spacepost/node";
   
   const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);
   
   const { data, error } = await spacepost.emails.send({
     from: "Acme <onboarding@test.spacepost.dev>",
     to: ["delivered@test.spacepost.dev"],
     subject: "Hello from SpacePost",
     html: "<strong>It works!</strong>",
   });
   
   if (error) {
     console.error(error); // { statusCode, name, message }
   } else {
     console.log("Sent", data.id);
   }

   cURL

   curl -X POST https://api.spacepost.dev/emails \
     -H "Authorization: Bearer $SPACEPOST_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "from": "Acme <onboarding@test.spacepost.dev>",
       "to": ["delivered@test.spacepost.dev"],
       "subject": "Hello from SpacePost",
       "html": "<strong>It works!</strong>"
     }'

   Python

   import os
   import requests
   
   r = requests.post(
       "https://api.spacepost.dev/emails",
       headers={"Authorization": f"Bearer {os.environ['SPACEPOST_API_KEY']}"},
       json={
           "from": "Acme <onboarding@test.spacepost.dev>",
           "to": ["delivered@test.spacepost.dev"],
           "subject": "Hello from SpacePost",
           "html": "<strong>It works!</strong>",
       },
   )
   print(r.status_code, r.json())

   Go

   package main
   
   import (
     "fmt"
     "io"
     "net/http"
     "os"
     "strings"
   )
   
   func main() {
     body := `{"from":"Acme <onboarding@test.spacepost.dev>","to":["delivered@test.spacepost.dev"],"subject":"Hello from SpacePost","html":"<strong>It works!</strong>"}`
     req, _ := http.NewRequest("POST", "https://api.spacepost.dev/emails", strings.NewReader(body))
     req.Header.Set("Authorization", "Bearer "+os.Getenv("SPACEPOST_API_KEY"))
     req.Header.Set("Content-Type", "application/json")
     res, err := http.DefaultClient.Do(req)
     if err != nil {
       panic(err)
     }
     defer res.Body.Close()
     out, _ := io.ReadAll(res.Body)
     fmt.Println(res.StatusCode, string(out))
   }

   响应为 { "id": "0192e1c4-7a3b-7c1e-9d2f-3b5a8e6f4c10" }。在控制台中打开这封邮件即可查看它的时间线：先是 sent，然后是 delivered。

3. 添加并验证你的域名

   要向任意收件人发送邮件，请使用你自己拥有的域名作为发件域名。

   curl -X POST https://api.spacepost.dev/domains \
     -H "Authorization: Bearer $SPACEPOST_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "name": "acme.com" }'

   响应会列出需要创建的 DNS records：三条 DKIM CNAME 记录，外加 send 子域名（自定义 return path）的一条 MX 记录和一条 TXT 记录。在你的 DNS 服务商处添加它们（Cloudflare、Route 53 等的指南），然后让 SpacePost 检查：

   curl -X POST https://api.spacepost.dev/domains/$DOMAIN_ID/verify \
     -H "Authorization: Bearer $SPACEPOST_API_KEY"

   或者让 CLI 代劳，并实时观察 DNS：

   npx spacepost domains doctor acme.com

   验证通常在几分钟内完成。DKIM 确认后，域名的 status 会变为 verified。

4. 从你的域名发送

   await spacepost.emails.send({
     from: "Acme <hello@acme.com>",
     to: ["you@example.com"],
     subject: "First real email",
     html: "<p>Sent from my own domain.</p>",
   });

新账户限制

新账户在前 7 天内每天最多发送 100 封邮件。参见账户沙盒。

下一步

按语言快速开始Next.js、Express、Hono、Python、Go、PHP、Ruby、Rust 等。

设置 Webhook及时了解邮件何时送达、退信或被打开。

送达率最佳实践进入收件箱，而不是垃圾邮件文件夹。