Enviar Email por Etiquetas

POST /api/messages/email/tags

Envía mensajes de correo electrónico a contactos que tienen etiquetas específicas asignadas. 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 EmailTagsMessagePayload extends EmailMessageBasePayload {
  tagIds: string[]; // Identificadores UUID de las etiquetas de contactos
}

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)
tagIds	string[]	Sí	Lista de IDs de etiquetas (UUID)

Ejemplo del cuerpo

{
  "subject": "Oferta exclusiva para clientes VIP",
  "message": "<h1>¡Solo para ti!</h1><p>Como cliente VIP, tienes acceso a esta oferta especial con 40% de descuento.</p><a href='#'>Aprovechar oferta</a>",
  "tagIds": ["vip-customers-uuid", "frequent-buyers-uuid"]
}

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-13579",
  "channel": "email",
  "messages": [
    {
      "id": "msg-uuid-1",
      "recipient": "[email protected]"
    },
    {
      "id": "msg-uuid-2",
      "recipient": "[email protected]"
    }
  ]
}

Sin destinatarios válidos (200 OK)

Cuando las etiquetas especificadas no tienen contactos asociados, el servicio responde con 200 OK, un queueId vacío y un array de messages vacío.

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

Ejemplos de uso

Fetch API

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

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

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

// Campaña para nuevos usuarios
const result = await sendEmailToTags('your-token', {
  subject: 'Bienvenido a SendMe - Guía de primeros pasos',
  message: `
    <div style="max-width: 600px; margin: 0 auto; font-family: Arial, sans-serif;">
      <h1 style="color: #007cba;">¡Bienvenido a SendMe!</h1>
      <p>Estamos emocionados de tenerte con nosotros. Aquí tienes una guía rápida para empezar:</p>

      <div style="background: #f8f9fa; padding: 20px; margin: 20px 0; border-radius: 8px;">
        <h3>Primeros pasos:</h3>
        <ol>
          <li>Configura tu perfil</li>
          <li>Importa tus contactos</li>
          <li>Envía tu primer mensaje</li>
        </ol>
      </div>

      <a href="#" style="background: #007cba; color: white; padding: 12px 24px; text-decoration: none; border-radius: 5px;">
        Comenzar ahora
      </a>
    </div>
  `,
  tagIds: ['new-users-uuid']
});

console.log(`Emails de bienvenida enviados: ${result.messages.length}`);

Axios

import axios from 'axios';

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

  return data;
}

// Recordatorio para usuarios inactivos
const result = await sendEmailToTags('your-token', {
  subject: 'Te extrañamos - Vuelve con un descuento especial',
  message: `
    Hola,

    Hemos notado que no has usado SendMe en las últimas semanas.

    Como agradecimiento por ser nuestro cliente, te ofrecemos un 25% de descuento
    en tu próxima recarga de créditos.

    Código: VUELVE25
    Válido hasta: 30 de Abril, 2024

    ¡Esperamos verte pronto!

    Equipo SendMe
  `,
  tagIds: ['inactive-users-uuid']
});

cURL

curl -X POST "/api/messages/email/tags" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "subject": "Evento exclusivo para suscriptores premium",
    "message": "<h1>Invitación exclusiva</h1><p>Estás invitado a nuestro evento virtual exclusivo para miembros premium.</p>",
    "tagIds": ["premium-members-uuid", "event-subscribers-uuid"]
  }'

Casos de uso avanzados

Segmentación por comportamiento

// Para usuarios que han abierto emails recientemente
await sendEmailToTags('your-token', {
  subject: 'Contenido personalizado basado en tus intereses',
  message: '<!-- Contenido dinámico basado en comportamiento -->',
  tagIds: ['email-openers-uuid', 'engaged-users-uuid']
});

// Para usuarios que han hecho clic en promociones anteriores
await sendEmailToTags('your-token', {
  subject: 'Nueva promoción que te va a encantar',
  message: '<!-- Promoción similar a sus intereses anteriores -->',
  tagIds: ['promo-clickers-uuid']
});

Campañas por industria o nicho

// Para clientes del sector salud
await sendEmailToTags('your-token', {
  subject: 'Nuevas regulaciones de comunicación en el sector salud',
  message: `
    <div style="max-width: 600px; margin: 0 auto;">
      <h2>Actualizaciones regulatorias importantes</h2>
      <p>Como profesional del sector salud, es importante que conozcas...</p>
      <!-- Contenido específico del sector -->
    </div>
  `,
  tagIds: ['healthcare-clients-uuid']
});

// Para e-commerce
await sendEmailToTags('your-token', {
  subject: 'Aumenta tus ventas con estas estrategias de email marketing',
  message: '<!-- Contenido específico para e-commerce -->',
  tagIds: ['ecommerce-clients-uuid']
});

Automatizaciones por fecha

// Felicitaciones de cumpleaños
await sendEmailToTags('your-token', {
  subject: '🎉 ¡Feliz cumpleaños! Aquí tienes un regalo',
  message: `
    <div style="text-align: center; padding: 40px;">
      <h1>🎂 ¡Feliz Cumpleaños!</h1>
      <p>Para celebrarte, te regalamos un 20% de descuento</p>
      <p>Código: <strong>CUMPLE20</strong></p>
    </div>
  `,
  tagIds: ['birthday-today-uuid']
});

Notas operacionales

• El backend elimina destinatarios duplicados por lote y omite silenciosamente destinos inválidos.
• Los contactos pueden tener múltiples etiquetas; el sistema evita envíos duplicados cuando un contacto cumple múltiples criterios de etiquetas.
• 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.
• Las campañas por etiquetas permiten una segmentación más precisa y mejores tasas de engagement.