Mail

Moduł Mail służy do wysyłania wiadomości e-mail z wnętrza modułu — powiadomień o zamówieniach, alertów o błędach synchronizacji, raportów itp. Wiadomość wysyła rdzeń Orbito, a nie sam moduł: nie potrzebujesz własnego serwera SMTP ani żadnej konfiguracji.

const { Mail } = require('@orbito/api-lib');

await Mail.sendMail(
  'klient@example.com',
  'Twoje zamówienie zostało wysłane',
  '<p>Zamówienie <b>#1234</b> zostało nadane.</p>'
);

Serwer nadawczy wybiera firma

Nie przekazujesz companyId ani danych serwera – platforma wysyła maila w kontekście firmy na podstawie tożsamości połączenia kontenera (szczegóły w Kontekst firmy). Firma w swoich ustawieniach wybiera, czy jej maile wychodzą przez serwer Orbito, czy przez jej własny serwer SMTP (z jej domeny i adresu). Dla modułu jest to przezroczyste – kod jest identyczny w obu przypadkach.

Mail.sendMail

await Mail.sendMail(to, subject, content, options?)

Parametr	Typ	Wymagany	Opis
`to`	`string`	Tak	Adres e-mail odbiorcy
`subject`	`string`	Tak	Temat wiadomości
`content`	`string`	Tak	Treść wiadomości w HTML (patrz niżej – to wnętrze szablonu, nie pełny dokument)
`options`	`object`	Nie	Opcje dodatkowe
`options.title`	`string`	Nie	Nagłówek wyświetlany nad treścią wiadomości
`options.replyTo`	`string`	Nie	Adres, na który trafią odpowiedzi odbiorcy

Zwraca Promise<{ messageId: string }> – identyfikator nadany przez serwer pocztowy.

const { Mail } = require('@orbito/api-lib');

// Minimalna wysyłka
await Mail.sendMail('klient@example.com', 'Potwierdzenie', '<p>Dziękujemy za zakup!</p>');

// Z nagłówkiem i adresem zwrotnym
await Mail.sendMail(
  'klient@example.com',
  'Twoje zamówienie zostało wysłane',
  `<p>Zamówienie <b>#${order.number}</b> zostało nadane.</p>
   <p>Numer śledzenia: ${order.trackingNumber}</p>`,
  {
    title: 'Zamówienie wysłane',
    replyTo: 'sklep@twojafirma.pl'
  }
);

Szablon i branding

Przekazany content nie jest wysyłany 1:1 – rdzeń opakowuje go w szablon graficzny Orbito: logo na górze, opcjonalny nagłówek (options.title), Twoja treść oraz stopka „Wiadomość wysłana przez moduł X w systemie Orbito".

Dlatego content powinien być fragmentem HTML (akapity, tabele, linki), a nie pełnym dokumentem:

// ❌ Nie wysyłaj pełnego dokumentu
await Mail.sendMail(to, subject, '<html><body><p>Treść</p></body></html>');

// ✅ Samo wnętrze
await Mail.sendMail(to, subject, '<p>Treść</p>');

Maile z szablonów firmy

Mail.sendMail wysyła treść, którą sam zbudujesz. Gdy właściciel firmy ma wysyłać maile o treści edytowanej w panelu (np. „Twoje zamówienie zostało nadane"), robi to wbudowana akcja automatyzacji send-template-email: renderuje zapisany szablon firmy i wysyła osobny mail na każdy adres odbiorcy (stały adres i/lub adres ze zmiennej). Wiadomość niesie HTML oraz automatycznie wygenerowaną wersję tekstową. Ta wersja jest dodawana tylko do maili z szablonów – Mail.sendMail wysyła sam HTML.

Moduł nie wywołuje tej akcji, tylko udostępnia szablonom swoje dane jako zmienne – patrz Templates.

Limity

Limit	Wartość
Maksymalny rozmiar treści	256 KB
Załączniki	Niedostępne
Liczba wiadomości	30 / minutę na firmę

Przekroczenie limitu lub błąd serwera pocztowego kończy się odrzuceniem promisy z Error – obsłuż to jak każdy inny błąd:

try {
  await Mail.sendMail(params.email, 'Raport dzienny', reportHtml);
} catch (err) {
  Log.error('Nie udało się wysłać raportu', { error: err.message });
}

Brak cichego fallbacku

Jeśli firma używa własnego serwera SMTP i serwer ten odrzuci wiadomość, błąd trafia do Twojego modułu – wiadomość nie zostanie automatycznie wysłana przez serwer Orbito. Firma świadomie wybrała własny serwer i sama odpowiada za jego poprawną konfigurację.

Dobre praktyki

Nie wysyłaj masowo – limit 30 wiadomości na minutę dotyczy całej firmy (wszystkich jej modułów łącznie). Do wysyłek marketingowych używaj dedykowanych narzędzi, a Mail traktuj jako kanał powiadomień transakcyjnych.

Waliduj adresy przed wysyłką – nieprawidłowy adres odbiorcy odrzuca wywołanie:

if (!customer.email) {
  Log.warn('Klient bez adresu e-mail, pomijam powiadomienie', { customerId: customer._id });
  return;
}
await Mail.sendMail(customer.email, subject, content);

Nie umieszczaj wrażliwych danych w treści – haseł, tokenów, pełnych numerów kart. Wiadomość e-mail nie jest bezpiecznym kanałem.