Referencia de 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]"],           // Opcional
  "bcc": ["[email protected]"],         // Opcional
  "reply_to": ["[email protected]"], // Opcional
  "subject": "Asunto del Correo",
  "html": "<h1>Contenido HTML</h1>",
  "text": "Contenido de texto plano",
  "attachments": [                    // Opcional
    {
      "filename": "document.pdf",
      "content": "base64_encoded_content",
      "content_type": "application/pdf"
    }
  ],
  "headers": {                        // Opcional
    "X-Custom-Header": "value"
  },
  "tags": {                           // Opcional
    "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": "Bienvenido a Zeabur Email",
    "html": "<h1>¡Bienvenido!</h1><p>Gracias por usar Zeabur Email.</p>"
  }'

// Ejemplo de 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: 'Prueba de Archivo Adjunto',
    html: '<p>Por favor vea el archivo adjunto</p>',
    attachments: [{
      filename: 'document.pdf',
      content: base64Content,
      content_type: 'application/pdf'
    }]
  })
});

POST /emails/schedule

{
  "from": "[email protected]",
  "to": ["[email protected]"],
  "cc": ["[email protected]"],              // Opcional
  "bcc": ["[email protected]"],            // Opcional
  "reply_to": ["[email protected]"],  // Opcional
  "subject": "Correo Programado",
  "html": "<h1>Contenido HTML</h1>",
  "text": "Contenido de texto plano",
  "attachments": [],                     // Opcional
  "headers": {},                         // Opcional
  "tags": {},                            // Opcional
  "scheduled_at": "2026-01-25T10:00:00Z" // Requerido, formato ISO 8601
}

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

GET /emails/scheduled

{
  "scheduled_emails": [
    {
      "id": "696de2c84210d814d66ee053",
      "from": "[email protected]",
      "to": ["[email protected]"],
      "subject": "Correo Programado",
      "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]"],       // Opcional
      "bcc": ["[email protected]"],      // Opcional
      "reply_to": ["[email protected]"], // Opcional
      "subject": "Correo Personalizado 1",
      "html": "<p>¡Hola, Usuario 1!</p>",
      "text": "¡Hola, Usuario 1!",         // Opcional
      "attachments": [],                   // Opcional
      "headers": {},                       // Opcional
      "tags": {"user_id": "1"}             // Opcional
    },
    {
      "from": "[email protected]",
      "to": ["[email protected]"],
      "subject": "Correo Personalizado 2",
      "html": "<p>¡Hola, Usuario 2!</p>"
    }
    // ... hasta 100 correos
  ]
}

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

{
  "error": "Descripción breve del error",
  "message": "Mensaje de error detallado"
}

{
  "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) {
        // Errores del cliente, no reintentar
        throw new Error(await response.text());
      }
      
      // Otros errores, reintentar después de esperar
      if (i < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000));
      }
    } catch (error) {
      if (i === maxRetries - 1) throw error;
    }
  }
}

// ✅ Recomendado
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: `Hola, ${user.name}`,
      html: `<p>Contenido personalizado</p>`
    }))
  })
});
 
// ❌ No recomendado
for (const user of users) {
  await fetch('https://api.zeabur.com/api/v1/zsend/emails', {
    // ... envío individual
  });
}

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