Send Email to All Contacts

POST /api/messages/email/all

Send email messages to all available contacts in your database. The operation is asynchronous: the API records every message in persistence, schedules delivery in BullMQ, and returns an enqueue summary.

Caution

This endpoint sends emails to all contacts with valid email addresses in your database. Use it carefully and ensure compliance with email marketing regulations.

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 EmailAllMessagePayload extends EmailMessageBasePayload {}

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)

Example Request Body

{
  "subject": "SendMe Newsletter - Important Updates",
  "message": "<h1>Hello Everyone!</h1><p>We want to share some important updates about our services...</p><p>Thank you for being part of our community.</p>"
}

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-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]"
    }
  ]
}

No Valid Recipients (200 OK)

When there are no contacts with valid emails in the database, the service responds with 200 OK, an empty queueId, and an empty messages array.

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

Usage Examples

Fetch API

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;
}

// Monthly newsletter
const result = await sendEmailToAll('your-token', {
  subject: 'SendMe Newsletter - March 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>March Newsletter</h1>
      </header>
      <main style="padding: 20px;">
        <h2>What's New This Month</h2>
        <p>This month we've added new features that will improve your experience...</p>

        <h3>New Features:</h3>
        <ul>
          <li>Enhanced message editor</li>
          <li>Advanced delivery reports</li>
          <li>Integration with new providers</li>
        </ul>
      </main>
      <footer style="background: #f8f9fa; padding: 15px; text-align: center; color: #666;">
        <p>If you don't want to receive these emails, <a href="#">click here</a></p>
      </footer>
    </div>
  `
});

console.log(`Newsletter sent to ${result.messages.length} contacts`);

Axios

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;
}

// Important announcement
const result = await sendEmailToAll('your-token', {
  subject: 'Important: Scheduled System Maintenance',
  message: `
    Dear Users,

    We're informing you about scheduled system maintenance:

    📅 Date: Saturday, April 20
    🕒 Time: 2:00 AM - 6:00 AM (GMT-5)

    During this time, services may be temporarily interrupted.

    Thank you for your understanding.

    SendMe Team
  `
});

cURL

curl -X POST "/api/messages/email/all" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "subject": "Happy Holidays from the SendMe Team",
    "message": "<h1>Happy Holidays!</h1><p>We want to wish you happy holidays and a prosperous new year. Thank you for trusting SendMe during this year.</p>"
  }'

Best Practices for Mass Email

Relevant and Personalized Content

const wellCraftedEmail = {
  subject: "Your Monthly Activity Summary - SendMe",
  message: `
    <div style="max-width: 600px; margin: 0 auto;">
      <h2>Hello {{name}},</h2>
      <p>Here's your monthly activity summary...</p>
      <!-- Relevant and valuable content -->
    </div>
  `
};

Legal Compliance

• Always include an unsubscribe option
• Respect local and international regulations (CAN-SPAM, GDPR)
• Maintain a clear privacy policy

Optimal Timing

// Consider sending when users are most active
// For example: Tuesday to Thursday, 10:00 AM - 2:00 PM

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.
• Important: Consider carefully the impact of sending to all contacts, especially for cost, content relevance, and email marketing regulation compliance.