REST API Reference

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]"],           // Optional
  "bcc": ["[email protected]"],         // Optional
  "reply_to": ["[email protected]"], // Optional
  "subject": "Email Subject",
  "html": "<h1>HTML Content</h1>",
  "text": "Plain text content",
  "attachments": [                    // Optional
    {
      "filename": "document.pdf",
      "content": "base64_encoded_content",
      "content_type": "application/pdf"
    }
  ],
  "headers": {                        // Optional
    "X-Custom-Header": "value"
  },
  "tags": {                           // Optional
    "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": "Welcome to Zeabur Email",
    "html": "<h1>Welcome!</h1><p>Thank you for using Zeabur Email.</p>"
  }'

// JavaScript example
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: 'Attachment Test',
    html: '<p>Please see the attachment</p>',
    attachments: [{
      filename: 'document.pdf',
      content: base64Content,
      content_type: 'application/pdf'
    }]
  })
});

POST /emails/schedule

{
  "from": "[email protected]",
  "to": ["[email protected]"],
  "cc": ["[email protected]"],              // Optional
  "bcc": ["[email protected]"],            // Optional
  "reply_to": ["[email protected]"],  // Optional
  "subject": "Scheduled Email",
  "html": "<h1>HTML Content</h1>",
  "text": "Plain text content",
  "attachments": [],                     // Optional
  "headers": {},                         // Optional
  "tags": {},                            // Optional
  "scheduled_at": "2026-01-25T10:00:00Z" // Required, ISO 8601 format
}

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

GET /emails/scheduled

{
  "scheduled_emails": [
    {
      "id": "696de2c84210d814d66ee053",
      "from": "[email protected]",
      "to": ["[email protected]"],
      "subject": "Scheduled Email",
      "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]"],       // Optional
      "bcc": ["[email protected]"],      // Optional
      "reply_to": ["[email protected]"], // Optional
      "subject": "Personalized Email 1",
      "html": "<p>Hello, User 1!</p>",
      "text": "Hello, User 1!",            // Optional
      "attachments": [],                   // Optional
      "headers": {},                       // Optional
      "tags": {"user_id": "1"}             // Optional
    },
    {
      "from": "[email protected]",
      "to": ["[email protected]"],
      "subject": "Personalized Email 2",
      "html": "<p>Hello, User 2!</p>"
    }
    // ... up to 100 emails
  ]
}

{
  "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": "Test Email",
      "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": "Test Email",
  "html": "<h1>Test</h1>",
  "text": "Test",
  "status": "delivered",
  "mal_status": "healthy",
  "created_at": "2026-01-20T08:00:00Z",
  "headers": {},
  "tags": {},
  "attachments": []
}

{
  "error": "Brief error description",
  "message": "Detailed 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) {
        // Client errors, don't retry
        throw new Error(await response.text());
      }
      
      // Other errors, retry after waiting
      if (i < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000));
      }
    } catch (error) {
      if (i === maxRetries - 1) throw error;
    }
  }
}

// ✅ Recommended
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: `Hello, ${user.name}`,
      html: `<p>Personalized content</p>`
    }))
  })
});
 
// ❌ Not recommended
for (const user of users) {
  await fetch('https://api.zeabur.com/api/v1/zsend/emails', {
    // ... single send
  });
}

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