📧 ExchangeMailbox - Node.js Email Client

Projekt Node.js implementujący klasę ExchangeMailbox do wysyłania wiadomości email przez Microsoft Graph API.

🚀 Funkcjonalności

✅ Klasa ExchangeMailbox z metodą sendMail
✅ Integracja z MS Graph API do wysyłania emaili
✅ Uwierzytelnianie przez Azure AD (MSAL)
✅ Konfiguracja przez zmienne środowiskowe (.env)
✅ Obsługa HTML i tekstowych emaili
✅ Wsparcie dla załączników
✅ Test połączenia z MS Graph API
✅ Przykłady użycia i testy

📋 Wymagania

Node.js 16+
Konto Microsoft 365 / Azure AD
Zarejestrowana aplikacja w Azure Portal
Uprawnienia administratora Azure AD (do zatwierdzenia uprawnień aplikacji)

🛠️ Instalacja

Sklonuj/pobierz projekt
Zainstaluj zależności:
```
npm install
```
Skonfiguruj zmienne środowiskowe (zobacz sekcję konfiguracja)
Uruchom test:
```
npm start
```

⚙️ Konfiguracja Azure AD

1. Rejestracja aplikacji w Azure Portal

Przejdź do Azure Portal
Wybierz Azure Active Directory > App registrations > New registration
Podaj nazwę aplikacji (np. "ExchangeMailbox App")
Wybierz Accounts in this organizational directory only
Kliknij Register

2. Konfiguracja uprawnień API

W zarejestrowanej aplikacji przejdź do API permissions
Kliknij Add a permission > Microsoft Graph > Application permissions
Dodaj uprawnienie:
- Mail.Send - do wysyłania emaili w imieniu aplikacji
Kliknij Grant admin consent (wymagane uprawnienia administratora)

Uwaga: Używamy uwierzytelniania aplikacji (Client Credentials flow), które pozwala aplikacji działać bez logowania użytkownika, ale wymaga uprawnień administratora.

3. Utworzenie Client Secret

Przejdź do Certificates & secrets
Kliknij New client secret
Podaj opis i wybierz okres ważności
Skopiuj wartość - będzie potrzebna w pliku .env

4. Skopiuj identyfikatory

Z sekcji Overview skopiuj:

Application (client) ID
Directory (tenant) ID

🔧 Konfiguracja zmiennych środowiskowych

Skopiuj plik .env i wypełnij następujące wartości:

# MS Graph API Configuration
AZURE_CLIENT_ID=your_client_id_here
AZURE_CLIENT_SECRET=your_client_secret_here
AZURE_TENANT_ID=your_tenant_id_here
SENDER_EMAIL=your_sender_email@yourdomain.com
TEST_RECIPIENT_EMAIL=test_recipient@example.com

Gdzie znaleźć te wartości:

AZURE_CLIENT_ID: Application ID z Azure Portal
AZURE_CLIENT_SECRET: Client Secret utworzony w Azure Portal
AZURE_TENANT_ID: Directory ID z Azure Portal
SENDER_EMAIL: Email użytkownika, który będzie nadawcą (musi istnieć w organizacji)
TEST_RECIPIENT_EMAIL: Email do testów (opcjonalne)

📖 Użycie

Podstawowy przykład

import { ExchangeMailbox } from './ExchangeMailbox.js'

const mailbox = new ExchangeMailbox()

// Wysłanie prostego emaila
const result = await mailbox.sendMail({
  to: 'odbiorca@example.com',
  subject: 'Temat wiadomości',
  body: 'Treść wiadomości'
})

if (result.success) {
  console.log('Email wysłany pomyślnie!')
} else {
  console.error('Błąd:', result.message)
}

Email z HTML

await mailbox.sendMail({
  to: 'odbiorca@example.com',
  subject: 'Email z HTML',
  body: '<h1>Witaj!</h1><p>To jest <strong>HTML</strong> email.</p>',
  bodyType: 'HTML'
})

Email z załącznikami

await mailbox.sendMail({
  to: 'odbiorca@example.com',
  subject: 'Email z załącznikiem',
  body: 'Zobacz załącznik w załączniku',
  attachments: [
    {
      name: 'dokument.pdf',
      contentBytes: 'base64_encoded_file_content',
      contentType: 'application/pdf'
    }
  ]
})

Test połączenia

const isConnected = await mailbox.testConnection()
if (isConnected) {
  console.log('Połączenie z MS Graph API działa!')
}

Uwaga: Test połączenia sprawdza czy można uzyskać token dostępu z Azure AD. Nie wymaga dodatkowych uprawnień API.

🏃 Uruchomienie testów

# Uruchomienie testów
npm start

# lub bezpośrednio
node main.js

📁 Struktura projektu

exchange-mailbox-nodejs/
├── 📄 ExchangeMailbox.js    # Główna klasa do wysyłania emaili
├── 📄 main.js              # Testy i przykłady użycia
├── 📄 package.json         # Konfiguracja NPM i zależności
├── 📄 .env                 # Zmienne środowiskowe (konfiguracja)
├── 📄 .gitignore          # Wykluczenia Git (chroni .env)
├── 📄 README.md           # Dokumentacja (ten plik)
└── 📁 .github/
    └── 📄 copilot-instructions.md  # Instrukcje dla Copilot

🔍 Rozwiązywanie problemów

Błędy uwierzytelniania

"Invalid client credentials" - sprawdź Client ID i Client Secret w pliku .env
"Invalid tenant" - sprawdź Tenant ID w pliku .env
"Insufficient privileges" - upewnij się że aplikacja ma uprawnienie Mail.Send i zostało zatwierdzone przez administratora

Błędy wysyłania emaili

"User not found" - sprawdź czy SENDER_EMAIL to prawdziwy użytkownik w organizacji
"Access denied" - sprawdź czy admin zatwierdził uprawnienia aplikacji
"Mailbox not found" - upewnij się że użytkownik ma licencję Exchange Online

Częste problemy podczas testów

"/me request is only valid with delegated authentication flow" - Ten błąd jest normalny, używamy uwierzytelniania aplikacji (client credentials)
"Insufficient privileges to complete the operation" - Nie jest potrzebne uprawnienie User.Read dla podstawowej funkcjonalności wysyłania emaili
"TypeError: _this.provider is not a function" - Problem z konfiguracją klienta Graph, rozwiązany w aktualnej wersji

Debugging

Test połączenia sprawdza czy można uzyskać token dostępu (nie wymaga dodatkowych uprawnień)
Włącz szczegółowe logi błędów w konsoli aby zobaczyć dokładne komunikaty z MS Graph API
Sprawdź czy wszystkie zmienne środowiskowe w .env są wypełnione

📦 Zależności

@azure/msal-node - Uwierzytelnianie Microsoft Authentication Library
@microsoft/microsoft-graph-client - Klient MS Graph API
dotenv - Ładowanie zmiennych środowiskowych

📄 Licencja

MIT License - możesz swobodnie używać, modyfikować i dystrybuować ten kod.

🆘 Pomoc

Jeśli napotkasz problemy:

Sprawdź konfigurację w Azure Portal
Zweryfikuj zmienne środowiskowe w .env
Uruchom test połączenia: await mailbox.testConnection()
Sprawdź logi błędów w konsoli

📧 Miłego wysyłania emaili z ExchangeMailbox! 🚀

Powrót do artykułu