REST API 参考

Authorization: Bearer zs_your_api_key_here

https://api.zeabur.com/api/v1/zsend

POST /emails

{
  "from": "[email protected]",
  "to": ["[email protected]"],
  "cc": ["[email protected]"],           // 可选
  "bcc": ["[email protected]"],         // 可选
  "reply_to": ["[email protected]"], // 可选
  "subject": "邮件主题",
  "html": "<h1>HTML 内容</h1>",
  "text": "纯文本内容",
  "attachments": [                    // 可选
    {
      "filename": "document.pdf",
      "content": "base64_encoded_content",
      "content_type": "application/pdf"
    }
  ],
  "headers": {                        // 可选
    "X-Custom-Header": "value"
  },
  "tags": {                           // 可选
    "campaign": "newsletter",
    "user_id": "12345"
  }
}

{
  "id": "696de2c84210d814d66ee052",
  "message_id": "",
  "status": "pending"
}

curl -X POST https://api.zeabur.com/api/v1/zsend/emails \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "from": "[email protected]",
    "to": ["[email protected]"],
    "subject": "欢迎使用 Zeabur Email",
    "html": "<h1>欢迎！</h1><p>感谢您使用 Zeabur Email。</p>"
  }'

// JavaScript 示例
const fs = require('fs');
 
const fileContent = fs.readFileSync('document.pdf');
const base64Content = fileContent.toString('base64');
 
const response = await fetch('https://api.zeabur.com/api/v1/zsend/emails', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    from: '[email protected]',
    to: ['[email protected]'],
    subject: '附件测试',
    html: '<p>请查看附件</p>',
    attachments: [{
      filename: 'document.pdf',
      content: base64Content,
      content_type: 'application/pdf'
    }]
  })
});

POST /emails/schedule

{
  "from": "[email protected]",
  "to": ["[email protected]"],
  "cc": ["[email protected]"],              // 可选
  "bcc": ["[email protected]"],            // 可选
  "reply_to": ["[email protected]"],  // 可选
  "subject": "定时邮件",
  "html": "<h1>HTML 内容</h1>",
  "text": "纯文本内容",
  "attachments": [],                     // 可选
  "headers": {},                         // 可选
  "tags": {},                            // 可选
  "scheduled_at": "2026-01-25T10:00:00Z" // 必填，ISO 8601 格式
}

{
  "id": "696de2c84210d814d66ee053",
  "status": "enqueued"
}

GET /emails/scheduled

{
  "scheduled_emails": [
    {
      "id": "696de2c84210d814d66ee053",
      "from": "[email protected]",
      "to": ["[email protected]"],
      "subject": "定时邮件",
      "scheduled_at": "2026-01-25T10:00:00Z",
      "status": "enqueued",
      "created_at": "2026-01-20T08:00:00Z",
      "attempts": 0
    }
  ],
  "total_count": 1
}

GET /emails/scheduled/:id

DELETE /emails/scheduled/:id

{
  "success": true,
  "message": "Scheduled email cancelled"
}

POST /emails/batch

{
  "emails": [
    {
      "from": "[email protected]",
      "to": ["[email protected]"],
      "cc": ["[email protected]"],       // 可选
      "bcc": ["[email protected]"],      // 可选
      "reply_to": ["[email protected]"], // 可选
      "subject": "个性化邮件 1",
      "html": "<p>你好，用户1！</p>",
      "text": "你好，用户1！",             // 可选
      "attachments": [],                   // 可选
      "headers": {},                       // 可选
      "tags": {"user_id": "1"}             // 可选
    },
    {
      "from": "[email protected]",
      "to": ["[email protected]"],
      "subject": "个性化邮件 2",
      "html": "<p>你好，用户2！</p>"
    }
    // ... 最多 100 封
  ]
}

{
  "job_id": "696de2c84210d814d66ee054",
  "status": "pending",
  "total_count": 2
}

GET /emails/batch

GET /emails/batch/:id

{
  "job_id": "696de2c84210d814d66ee054",
  "total_count": 100,
  "sent_count": 95,
  "failed_count": 5,
  "status": "completed",
  "created_at": "2026-01-20T08:00:00Z",
  "completed_at": "2026-01-20T08:15:00Z"
}

GET /emails

{
  "data": [
    {
      "id": "696de2c84210d814d66ee052",
      "from": "[email protected]",
      "to": ["[email protected]"],
      "subject": "测试邮件",
      "status": "delivered",
      "created_at": "2026-01-20T08:00:00Z"
    }
  ],
  "total": 1
}

GET /emails/:id

{
  "id": "696de2c84210d814d66ee052",
  "message_id": "0111019bd53de187-bda14a71-25a3-4fdc-a1a0-f543ff58c085-000000",
  "from": "[email protected]",
  "to": ["[email protected]"],
  "cc": [],
  "bcc": [],
  "reply_to": [],
  "subject": "测试邮件",
  "html": "<h1>测试</h1>",
  "text": "测试",
  "status": "delivered",
  "mal_status": "healthy",
  "created_at": "2026-01-20T08:00:00Z",
  "headers": {},
  "tags": {},
  "attachments": []
}

{
  "error": "错误简短描述",
  "message": "详细错误信息"
}

{
  "error": "validation error",
  "message": "subject length (1200) exceeds maximum (998 characters)"
}

{
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}

{
  "error": "permission denied",
  "message": "API key does not have permission to send from this domain"
}

{
  "error": "daily quota exceeded (55/55), resets at 2026-01-23 00:00:00"
}

async function sendEmailWithRetry(emailData, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch('https://api.zeabur.com/api/v1/zsend/emails', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': 'Bearer YOUR_API_KEY'
        },
        body: JSON.stringify(emailData)
      });
      
      if (response.ok) {
        return await response.json();
      }
      
      if (response.status === 400 || response.status === 403) {
        // 客户端错误，不重试
        throw new Error(await response.text());
      }
      
      // 其他错误，等待后重试
      if (i < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000));
      }
    } catch (error) {
      if (i === maxRetries - 1) throw error;
    }
  }
}

// ✅ 推荐
await fetch('https://api.zeabur.com/api/v1/zsend/emails/batch', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    emails: users.map(user => ({
      from: '[email protected]',
      to: [user.email],
      subject: `你好，${user.name}`,
      html: `<p>个性化内容</p>`
    }))
  })
});
 
// ❌ 不推荐
for (const user of users) {
  await fetch('https://api.zeabur.com/api/v1/zsend/emails', {
    // ... 单封发送
  });
}

{
  "tags": {
    "campaign": "welcome_series",
    "user_segment": "new_users",
    "template_version": "v2"
  }
}