Send Email to Specific Contacts

POST /api/messages/email/contacts

Send email messages to a specific list of email addresses. The operation is asynchronous: the API records every message in persistence, schedules delivery in BullMQ, and returns an enqueue summary.

Authentication

• Include the bearer token in Authorization: Bearer <token>.
• Only members that accepted the current terms can trigger messaging actions; otherwise the service returns 403 Forbidden.

Request Body

interface EmailContactsMessagePayload extends EmailMessageBasePayload {
  contacts: string[]; // Explicit list of email addresses
}

interface EmailMessageBasePayload {
  subject: string;
  message: string; // HTML or plain text supported by the provider
}

Field	Type	Required	Description
subject	string	Yes	Email subject
message	string	Yes	Email content (HTML or plain text)
contacts	string[]	Yes	List of email addresses

Example Request Body

{
  "subject": "Welcome to SendMe - Registration Confirmation",
  "message": "<h1>Welcome!</h1><p>Your account has been successfully created. Thank you for joining SendMe.</p>",
  "contacts": ["[email protected]", "[email protected]"]
}

Response

The API responds with the shared MessageEnqueueResultDto contract:

interface MessageEnqueueResultDto {
  queueId: string; // BullMQ job identifier, empty when nothing was enqueued
  channel: 'email';
  messages: Array<{
    id: string; // UUID of the persisted message
    recipient: string; // Email address normalized by the backend
  }>;
}

Successful Response (201 Created)

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

No Valid Recipients (200 OK)

When the request does not resolve any valid email addresses, the service responds with 200 OK, an empty queueId, and an empty messages array.

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

Usage Examples

Fetch API

async function sendEmailToContacts(token: string, payload: EmailContactsMessagePayload) {
  const response = await fetch('/api/messages/email/contacts', {
    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;
}

// Usage with HTML
const result = await sendEmailToContacts('your-token', {
  subject: 'Invoice for your order #12345',
  message: `
    <div style="font-family: Arial, sans-serif;">
      <h2>Thank you for your purchase</h2>
      <p>Attached you will find the invoice for your order.</p>
      <a href="#" style="background: #007cba; color: white; padding: 10px 20px; text-decoration: none;">
        View Order
      </a>
    </div>
  `,
  contacts: ['[email protected]']
});

console.log(`Emails enqueued: ${result.messages.length}`);

Axios

import axios from 'axios';

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

  return data;
}

// Usage with plain text
const result = await sendEmailToContacts('your-token', {
  subject: 'Password Recovery',
  message: 'We received a request to reset your password. If this was not you, please ignore this email.',
  contacts: ['[email protected]']
});

cURL

curl -X POST "/api/messages/email/contacts" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "subject": "SendMe Newsletter - Monthly Updates",
    "message": "<h1>Updates</h1><p>Discover the new features we'\''ve added this month.</p>",
    "contacts": ["[email protected]", "[email protected]"]
  }'

Supported Content Types

HTML Email

const htmlPayload = {
  subject: "Special Promotion",
  message: `
    <html>
      <body>
        <div style="max-width: 600px; margin: 0 auto;">
          <h1 style="color: #333;">Special Offer!</h1>
          <p>Don't miss our end-of-season promotion.</p>
          <img src="https://example.com/promotion.jpg" alt="Promotion" style="max-width: 100%;">
          <a href="https://store.example.com" style="background: #ff6b6b; color: white; padding: 15px 25px; text-decoration: none; border-radius: 5px;">
            Shop Now
          </a>
        </div>
      </body>
    </html>
  `,
  contacts: ["[email protected]"]
};

Plain Text Email

const textPayload = {
  subject: "Appointment Confirmation",
  message: `
    Dear Customer,

    Your appointment has been confirmed for:
    Date: April 15, 2024
    Time: 10:00 AM
    Location: Main Office

    If you need to reschedule, please reply to this email.

    Best regards,
    SendMe Team
  `,
  contacts: ["[email protected]"]
};

Operational Notes

• The backend removes duplicated recipients per batch and silently skips invalid destinations.
• Balance validation runs before queuing; insufficient credits return an error response without enqueuing messages.
• Use the returned queueId to correlate delivery status inside the admin UI or via dedicated status endpoints.
• Each message persists provider metadata and can be audited through the messaging module filters.
• HTML content must be valid and compatible with major email clients.