Enviar Email a Todos los Contactos

POST /api/messages/email/all

Envía mensajes de correo electrónico a todos los contactos disponibles en tu base de datos. La operación es asíncrona: la API registra cada mensaje en la persistencia, programa la entrega en BullMQ y retorna un resumen del encolado.

Autenticación

Incluye el token bearer en Authorization: Bearer <token>.
Solo los miembros que han aceptado los términos actuales pueden activar acciones de mensajería; de lo contrario, el servicio retorna 403 Forbidden.

Cuerpo de la petición

interface EmailAllMessagePayload extends EmailMessageBasePayload {}

interface EmailMessageBasePayload {
  subject: string;
  message: string; // HTML o texto plano soportado por el proveedor
}

Campo	Tipo	Requerido	Descripción
`subject`	string	Sí	Asunto del email
`message`	string	Sí	Contenido del email (HTML o texto plano)

Ejemplo del cuerpo

{
  "subject": "Newsletter SendMe - Actualizaciones importantes",
  "message": "<h1>¡Hola a todos!</h1><p>Queremos compartir algunas actualizaciones importantes sobre nuestros servicios...</p><p>Gracias por ser parte de nuestra comunidad.</p>"
}

Respuesta

La API responde con el contrato compartido MessageEnqueueResultDto:

interface MessageEnqueueResultDto {
  queueId: string; // Identificador del job de BullMQ, vacío cuando no se encoló nada
  channel: 'email';
  messages: Array<{
    id: string; // UUID del mensaje persistido
    recipient: string; // Dirección de email normalizada por el backend
  }>;
}

Respuesta exitosa (201 Created)

{
  "queueId": "email-queue-67890",
  "channel": "email",
  "messages": [
    {
      "id": "msg-uuid-1",
      "recipient": "[email protected]"
    },
    {
      "id": "msg-uuid-2",
      "recipient": "[email protected]"
    },
    {
      "id": "msg-uuid-3",
      "recipient": "[email protected]"
    }
  ]
}

Sin destinatarios válidos (200 OK)

Cuando no existen contactos con emails válidos en la base de datos, el servicio responde con 200 OK, un queueId vacío y un array de messages vacío.

{
  "queueId": "",
  "channel": "email",
  "messages": []
}

Ejemplos de uso

async function sendEmailToAll(token: string, payload: EmailAllMessagePayload) {
  const response = await fetch('/api/messages/email/all', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${token}`,
    },
    body: JSON.stringify(payload),
  });

  if (!response.ok) {
    throw new Error(`Email broadcast failed: ${response.status}`);
  }

  const data: MessageEnqueueResultDto = await response.json();
  return data;
}

// Newsletter mensual
const result = await sendEmailToAll('your-token', {
  subject: 'SendMe Newsletter - Marzo 2024',
  message: `
    <div style="max-width: 600px; margin: 0 auto; font-family: Arial, sans-serif;">
      <header style="background: #007cba; color: white; padding: 20px; text-align: center;">
        <h1>Newsletter Marzo</h1>
      </header>
      <main style="padding: 20px;">
        <h2>Novedades del mes</h2>
        <p>Este mes hemos añadido nuevas funciones que facilitarán tu experiencia...</p>

        <h3>Nuevas características:</h3>
        <ul>
          <li>Editor mejorado de mensajes</li>
          <li>Reportes avanzados de entrega</li>
          <li>Integración con nuevos proveedores</li>
        </ul>
      </main>
      <footer style="background: #f8f9fa; padding: 15px; text-align: center; color: #666;">
        <p>Si no deseas recibir estos emails, <a href="#">haz clic aquí</a></p>
      </footer>
    </div>
  `
});

console.log(`Newsletter enviada a ${result.messages.length} contactos`);

import axios from 'axios';

async function sendEmailToAll(token: string, payload: EmailAllMessagePayload) {
  const { data } = await axios.post<MessageEnqueueResultDto>(
    '/api/messages/email/all',
    payload,
    {
      headers: {
        Authorization: `Bearer ${token}`,
      },
    },
  );

  return data;
}

// Anuncio importante
const result = await sendEmailToAll('your-token', {
  subject: 'Importante: Mantenimiento programado del sistema',
  message: `
    Estimados usuarios,

    Les informamos que realizaremos un mantenimiento programado del sistema:

    📅 Fecha: Sábado 20 de Abril
    🕒 Horario: 2:00 AM - 6:00 AM (GMT-5)

    Durante este tiempo, los servicios podrán verse interrumpidos temporalmente.

    Agradecemos su comprensión.

    Equipo SendMe
  `
});

curl -X POST "/api/messages/email/all" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "subject": "Felices fiestas de parte del equipo SendMe",
    "message": "<h1>¡Felices Fiestas!</h1><p>Queremos desearles unas felices fiestas y un próspero año nuevo. Gracias por confiar en SendMe durante este año.</p>"
  }'

Mejores prácticas para email masivo

Contenido relevante y personalizado

const wellCraftedEmail = {
  subject: "Tu resumen mensual de actividad - SendMe",
  message: `
    <div style="max-width: 600px; margin: 0 auto;">
      <h2>Hola {{name}},</h2>
      <p>Aquí tienes tu resumen de actividad del mes...</p>
      <!-- Contenido relevante y valioso -->
    </div>
  `
};

Cumplimiento legal

Incluye siempre una opción de desuscripción
Respeta las regulaciones locales e internacionales (CAN-SPAM, GDPR)
Mantén una política clara de privacidad

Horarios óptimos

// Considera enviar en horarios cuando los usuarios están más activos
// Por ejemplo: martes a jueves, 10:00 AM - 2:00 PM

Notas operacionales

El backend elimina destinatarios duplicados por lote y omite silenciosamente destinos inválidos.
La validación del saldo se ejecuta antes del encolado; créditos insuficientes retornan una respuesta de error sin encolar mensajes.
Usa el queueId retornado para correlacionar el estado de entrega dentro de la UI de administración o vía endpoints de estado dedicados.
Cada mensaje persiste metadatos del proveedor y puede ser auditado a través de los filtros del módulo de mensajería.
Importante: Considera cuidadosamente el impacto de enviar a todos los contactos, especialmente para el costo, la relevancia del contenido y el cumplimiento de regulaciones de email marketing.