v1.0.0

Email API

API RESTful para envio de correos electronicos con soporte completo para hilos de conversacion, HTML, CC, BCC y adjuntos.

Ver Documentacion Comenzar 
curl -X POST https://email-api.cubeark.dev/api/v1/email/send \
  -H "Content-Type: application/json" \
  -d '{"smtp": {...}, "to": [...], "subject": "Hola", "html_body": "<h1>Hola Mundo</h1>"}'

Caracteristicas

HTML Completo

Soporte completo para contenido HTML con fallback automatico a texto plano.

CC y BCC

Envia correos con destinatarios en copia y copia oculta.

Hilos de Conversacion

Responde en el mismo hilo manteniendo el contexto de la conversacion.

Adjuntos Base64

Envia archivos adjuntos codificados en Base64 con tipos MIME personalizados.

Envio Masivo

Envia multiples correos en una sola peticion con configuracion compartida.

SMTP Dinamico

Configura diferentes servidores SMTP por cada request.

Instalacion

Terminal 
# Clonar repositorio
git clone https://github.com/abraham-developer/email-api.git
cd email-api

# Instalar dependencias
go mod download

# Ejecutar
go run cmd/server/main.go
Terminal 
# Construir imagen
docker build -t email-api:latest .

# Ejecutar contenedor
docker run -d -p 8080:8080 --name email-api email-api:latest
Terminal 
# Iniciar servicios
docker-compose up -d

# Ver logs
docker-compose logs -f

# Detener
docker-compose down

Endpoints

Metodo Endpoint Descripcion
GET /api/v1/health Verificar estado del servicio
POST /api/v1/email/send Enviar un correo electronico
POST /api/v1/email/reply Responder en un hilo existente
POST /api/v1/email/outlook-reply Responder en hilo (optimizado para Outlook)
POST /api/v1/email/bulk Envio masivo de correos
GET /api/v1/health

Verifica que el servicio este funcionando correctamente.

Respuesta

{
  "status": "ok",
  "message": "Email API is running",
  "version": "1.0.0"
}
POST /api/v1/email/send

Envia un correo electronico con soporte para HTML, CC, BCC y adjuntos.

Cuerpo de la Peticion

Campo Tipo Requerido Descripcion
smtp SMTPConfig Si Configuracion del servidor SMTP
to EmailAddress[] Si Lista de destinatarios
cc EmailAddress[] No Destinatarios en copia
bcc EmailAddress[] No Destinatarios en copia oculta
subject string Si Asunto del correo
html_body string Si Contenido HTML del correo
text_body string No Texto plano alternativo
reply_to EmailAddress No Direccion para respuestas
attachments Attachment[] No Archivos adjuntos

Respuesta Exitosa

{
  "success": true,
  "message": "Correo enviado exitosamente",
  "data": {
    "success": true,
    "message_id": "<[email protected]>",
    "message": "Correo enviado exitosamente",
    "sent_to": 1
  }
}
POST /api/v1/email/reply

Responde a un correo existente manteniendo el hilo de conversacion.

Campos Adicionales

Campo Tipo Requerido Descripcion
original_message_id string Si Message-ID del correo original
POST /api/v1/email/bulk

Envia multiples correos en una sola peticion con configuracion SMTP compartida.

Cuerpo de la Peticion

Campo Tipo Requerido Descripcion
smtp SMTPConfig Si Configuracion SMTP compartida
emails EmailItem[] Si Array de correos a enviar

Respuesta

{
  "success": true,
  "data": {
    "total_sent": 2,
    "total_failed": 0,
    "results": [...]
  }
}

Modelos de Datos

SMTPConfig

Configuracion del servidor SMTP para el envio de correos.

interface SMTPConfig {
  host: string;        // Servidor SMTP (ej: smtp.gmail.com)
  port: number;        // Puerto (ej: 587)
  username: string;    // Usuario de autenticacion
  password: string;    // Contrasena o App Password
  from_name?: string;  // Nombre del remitente
  from_email: string;  // Email del remitente
  use_tls?: boolean;   // Usar TLS (recomendado: true)
}

EmailAddress

Representa una direccion de correo electronico.

interface EmailAddress {
  name?: string;    // Nombre del contacto
  address: string;  // Direccion de email
}

Attachment

Archivo adjunto codificado en Base64.

interface Attachment {
  filename: string;      // Nombre del archivo
  content_type?: string; // Tipo MIME
  content: string;       // Contenido en Base64
}

Ejemplos de Uso

cURL 
curl -X POST https://email-api.cubeark.dev/api/v1/email/send \
  -H "Content-Type: application/json" \
  -d '{
    "smtp": {
      "host": "smtp.gmail.com",
      "port": 587,
      "username": "[email protected]",
      "password": "tu-app-password",
      "from_name": "Sistema",
      "from_email": "[email protected]",
      "use_tls": true
    },
    "to": [
      {"name": "Juan Perez", "address": "[email protected]"}
    ],
    "subject": "Prueba de correo",
    "html_body": "<h1>Hola Juan</h1><p>Este es un correo de <strong>prueba</strong>.</p>"
  }'
cURL 
curl -X POST https://email-api.cubeark.dev/api/v1/email/send \
  -H "Content-Type: application/json" \
  -d '{
    "smtp": {
      "host": "smtp.gmail.com",
      "port": 587,
      "username": "[email protected]",
      "password": "tu-password",
      "from_email": "[email protected]",
      "use_tls": true
    },
    "to": [
      {"name": "Cliente", "address": "[email protected]"}
    ],
    "cc": [
      {"name": "Gerente", "address": "[email protected]"}
    ],
    "bcc": [
      {"address": "[email protected]"}
    ],
    "subject": "Reporte Mensual",
    "html_body": "<h2>Reporte</h2><p>Contenido del reporte.</p>"
  }'
cURL 
curl -X POST https://email-api.cubeark.dev/api/v1/email/reply \
  -H "Content-Type: application/json" \
  -d '{
    "smtp": {
      "host": "smtp.gmail.com",
      "port": 587,
      "username": "[email protected]",
      "password": "tu-password",
      "from_email": "[email protected]"
    },
    "original_message_id": "<[email protected]>",
    "to": [
      {"name": "Cliente", "address": "[email protected]"}
    ],
    "subject": "Reporte Mensual",
    "html_body": "<p>Gracias por tu mensaje. Aqui esta la informacion adicional.</p>"
  }'
cURL 
curl -X POST https://email-api.cubeark.dev/api/v1/email/bulk \
  -H "Content-Type: application/json" \
  -d '{
    "smtp": {
      "host": "smtp.gmail.com",
      "port": 587,
      "username": "[email protected]",
      "password": "tu-password",
      "from_email": "[email protected]"
    },
    "emails": [
      {
        "to": [{"address": "[email protected]"}],
        "subject": "Oferta especial",
        "html_body": "<p>Oferta personalizada para ti</p>"
      },
      {
        "to": [{"address": "[email protected]"}],
        "subject": "Oferta especial",
        "html_body": "<p>Oferta personalizada para ti</p>"
      }
    ]
  }'
cURL 
curl -X POST https://email-api.cubeark.dev/api/v1/email/send \
  -H "Content-Type: application/json" \
  -d '{
    "smtp": {
      "host": "smtp.gmail.com",
      "port": 587,
      "username": "[email protected]",
      "password": "tu-password",
      "from_email": "[email protected]",
      "use_tls": true
    },
    "to": [
      {"address": "[email protected]"}
    ],
    "subject": "Documento adjunto",
    "html_body": "<p>Te envio el documento solicitado.</p>",
    "attachments": [
      {
        "filename": "documento.pdf",
        "content_type": "application/pdf",
        "content": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC9UeXBlL..."
      }
    ]
  }'

Configuracion SMTP

Gmail

Host: smtp.gmail.com

Puerto: 587

TLS: Si

Importante: Usa "App Password" en lugar de tu contrasena normal. Crear App Password

Office 365 / Outlook

Host: smtp.office365.com

Puerto: 587

TLS: Si

SendGrid

Host: smtp.sendgrid.net

Puerto: 587

Usuario: apikey

Password: Tu API Key

Otros Proveedores

Yahoo: smtp.mail.yahoo.com:587

Mailgun: smtp.mailgun.org:587

Amazon SES: email-smtp.[region].amazonaws.com:587

Probar la API

Respuesta

La respuesta aparecera aqui...