Zeabur EmailAPI Key Management

API Key Management

API keys are used to authenticate your Zeabur Email API requests. Each key can have different permission levels.

Permission Types

Zeabur Email provides three permission levels:

Permission TypeDescriptionUse Cases
Read Only (read_only)Can only query emails and statisticsData analysis, monitoring dashboards
Send Only (send_only)Can send emails and query statusProduction applications (recommended)
All Permissions (all)Includes all operation permissionsManagement tools, development environments
⚠️

For security reasons, it is recommended to use “Send Only” permission in production and avoid using “All Permissions”.

Creating API Keys

Log in to Console

Visit the Zeabur Email management page in the Zeabur console.

Create New Key

  1. Go to “API Key Management”
  2. Click “Create API Key”
  3. Enter key name (for identification)
  4. Select permission type
  5. (Optional) Restrict to specific domains
  6. Click “Create”

Save the Key

🚫

The key is only shown once during creation! Save it to a secure location immediately.

After creation, the system will display the complete API key. Copy and save it securely - you won’t be able to view it again.

Domain Restrictions

You can restrict an API key to only send emails from specific domains for enhanced security:

// Set allowed domains when creating the key
{
  "name": "Production API Key",
  "permission": "send_only",
  "allowed_domains": ["yourdomain.com", "mail.yourdomain.com"]
}

This way, even if the key is leaked, attackers cannot use unauthorized domains to send emails.

Using API Keys

HTTP Request Header

Include the key in all API requests:

POST /api/v1/zsend/emails
Host: api.zeabur.com
Content-Type: application/json
Authorization: Bearer zs_your_api_key_here
 
{
  "from": "[email protected]",
  ...
}

Code Examples

JavaScript

const apiKey = process.env.ZSEND_API_KEY;
 
const response = await fetch('https://api.zeabur.com/api/v1/zsend/emails', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ' + apiKey
  },
  body: JSON.stringify({
    from: '[email protected]',
    to: ['[email protected]'],
    subject: 'Test Email',
    html: '<p>Test Content</p>'
  })
});

Python

import os
import requests
 
api_key = os.environ.get('ZSEND_API_KEY')
 
response = requests.post(
    'https://api.zeabur.com/api/v1/zsend/emails',
    headers={
        'Content-Type': 'application/json',
        'Authorization': 'Bearer ' + api_key
    },
    json={
        'from': '[email protected]',
        'to': ['[email protected]'],
        'subject': 'Test Email',
        'html': '<p>Test Content</p>'
    }
)

Go

package main
 
import (
    "bytes"
    "encoding/json"
    "net/http"
    "os"
)
 
func sendEmail() error {
    apiKey := os.Getenv("ZSEND_API_KEY")
    
    payload := map[string]interface{}{
        "from":    "[email protected]",
        "to":      []string{"[email protected]"},
        "subject": "Test Email",
        "html":    "<p>Test Content</p>",
    }
    
    jsonData, _ := json.Marshal(payload)
    req, _ := http.NewRequest("POST", "https://api.zeabur.com/api/v1/zsend/emails", bytes.NewBuffer(jsonData))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Authorization", "Bearer " + apiKey)
    
    client := &http.Client{}
    resp, err := client.Do(req)
    return err
}

Key Rotation

Regular API key rotation is a good security practice:

Create New Key

Create a new API key while keeping the old key active.

Update Application Configuration

Gradually update the API key in your applications to the new key.

Delete Old Key

After confirming all applications have been updated, delete the old key.

It is recommended to rotate keys every 90 days.

Revoking Keys

If a key is leaked or no longer needed:

  1. Go to “API Key Management”
  2. Find the key to delete
  3. Click the “Delete” button
  4. Confirm deletion
⚠️

After deleting a key, all API requests using that key will immediately fail.

Security Best Practices

1. Use Environment Variables

Never hardcode API keys in your code:

// ❌ Not recommended: Don't hardcode
const apiKey = 'zs_xxxxxxxxxxxxxxxxxxxxxxxx';
 
// ✅ Recommended: Use environment variables
const apiKey = process.env.ZSEND_API_KEY;

2. Use Principle of Least Privilege

Create separate keys with appropriate permissions for different applications:

  • Production Apps: Send-only permission + domain restrictions
  • Data Analysis: Read-only permission
  • Admin Tools: All permissions (only when necessary)

3. Monitor Key Usage

View usage statistics for each key in the Zeabur Email console:

  • Request count
  • Email sent count
  • Error rate

Revoke the key immediately if abnormal usage is detected.

4. Don’t Share Keys

Create separate keys for each application and environment (development/production) for easier tracking and management.

Troubleshooting

401 Unauthorized

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

Possible causes:

  • API key is incorrect or has been deleted
  • Request header format is wrong (should be Authorization: Bearer <token>)
  • Key has leading/trailing spaces or missing Bearer prefix

403 Forbidden

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

Possible causes:

  • Insufficient key permissions (e.g., using read-only key to send emails)
  • Sender domain is not in the key’s allowed list
  • Domain is not verified

429 Too Many Requests

{
  "error": "too many requests",
  "message": "Rate limit exceeded"
}

Solutions:

  • Implement request throttling and retry mechanisms
  • Consider upgrading your account for higher rate limits
  • Use batch sending API to reduce request count
Domain ManagementWebhook Configuration