Gestión de Claves API

Las claves API se utilizan para autenticar sus solicitudes API de Zeabur Email. Cada clave puede tener diferentes niveles de permiso.

Tipos de Permisos

Zeabur Email proporciona tres niveles de permiso:

Crear Claves API

Restricciones de Dominio

Puede restringir una clave API para que solo envíe correos desde dominios específicos para mayor seguridad:

// Establecer dominios permitidos al crear la clave
{
  "name": "Production API Key",
  "permission": "send_only",
  "allowed_domains": ["yourdomain.com", "mail.yourdomain.com"]
}

De esta manera, incluso si la clave se filtra, los atacantes no pueden usar dominios no autorizados para enviar correos.

Usar Claves API

Encabezado de Solicitud HTTP

Incluya la clave en todas las solicitudes API:

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

Ejemplos de Código

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: 'Correo de Prueba',
    html: '<p>Contenido de Prueba</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': 'Correo de Prueba',
        'html': '<p>Contenido de Prueba</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": "Correo de Prueba",
        "html":    "<p>Contenido de Prueba</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
}

Rotación de Claves

La rotación regular de claves API es una buena práctica de seguridad:

Se recomienda rotar las claves cada 90 días.

Revocar Claves

Si una clave se filtra o ya no se necesita:

1. Vaya a “Gestión de Claves API”
2. Encuentre la clave a eliminar
3. Haga clic en el botón “Eliminar”
4. Confirme la eliminación

Mejores Prácticas de Seguridad

1. Usar Variables de Entorno

Nunca codifique las claves API en su código:

// ❌ No recomendado: No codificar directamente
const apiKey = 'zs_xxxxxxxxxxxxxxxxxxxxxxxx';
 
// ✅ Recomendado: Usar variables de entorno
const apiKey = process.env.ZSEND_API_KEY;

2. Usar Principio de Menor Privilegio

Cree claves separadas con permisos apropiados para diferentes aplicaciones:

• Aplicaciones de Producción: Permiso de solo envío + restricciones de dominio
• Análisis de Datos: Permiso de solo lectura
• Herramientas de Administración: Todos los permisos (solo cuando sea necesario)

3. Monitorear Uso de Claves

Vea estadísticas de uso para cada clave en la consola de Zeabur Email:

• Cantidad de solicitudes
• Cantidad de correos enviados
• Tasa de error

Revoque la clave inmediatamente si se detecta un uso anormal.

4. No Compartir Claves

Cree claves separadas para cada aplicación y entorno (desarrollo/producción) para facilitar el seguimiento y la gestión.

Solución de Problemas

401 Unauthorized

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

Posibles causas:

• La clave API es incorrecta o ha sido eliminada
• El formato del encabezado de solicitud es incorrecto (debe ser Authorization: Bearer <token>)
• La clave tiene espacios al principio/final o falta el prefijo Bearer

403 Forbidden

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

Posibles causas:

• Permisos de clave insuficientes (por ejemplo, usar clave de solo lectura para enviar correos)
• El dominio del remitente no está en la lista permitida de la clave
• El dominio no está verificado

429 Too Many Requests

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

Soluciones:

• Implementar mecanismos de limitación y reintento de solicitudes
• Considere actualizar su cuenta para obtener límites de tasa más altos
• Use la API de envío por lotes para reducir el número de solicitudes