Yaltopia-Ticket-Email/docs/API.md

# API Reference

## Base URL
```
http://localhost:3001  # Development
https://your-domain.com  # Production
```

## Authentication
No authentication required. Security is handled through:
- Rate limiting (10 requests per 15 minutes by default)
- Input validation
- CORS restrictions

## Rate Limiting
- **Default**: 10 emails per 15 minutes per IP
- **Headers**: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
- **Error**: 429 Too Many Requests

## Content Type
All requests must use `Content-Type: application/json`

---

## Endpoints

### Health Check
Check service status and availability.

```http
GET /health
```

**Response:**
```json
{
  "status": "healthy",
  "timestamp": "2026-03-12T10:00:00.000Z",
  "service": "email-template-service",
  "version": "1.0.0"
}
```

**Status Codes:**
- `200` - Service healthy
- `503` - Service unhealthy

---

### API Information
Get API information and rate limits.

```http
GET /api
```

**Response:**
```json
{
  "service": "Email Template Service",
  "version": "1.0.0",
  "endpoints": {
    "POST /api/emails/invitation": "Send invitation email",
    "POST /api/emails/payment-request": "Send payment request email",
    "POST /api/emails/password-reset": "Send password reset email"
  },
  "rateLimit": {
    "max": 10,
    "windowMs": 900000
  }
}
```

---

### Send Invitation Email
Send event invitation emails with RSVP functionality.

```http
POST /api/emails/invitation
```

**Request Body:**
```json
{
  "to": "user@example.com",
  "eventName": "Product Launch Event",
  "dateTime": "March 25, 2026 at 2:00 PM",
  "location": "Conference Room A",
  "ctaUrl": "https://myapp.com/rsvp/123",
  "ctaLabel": "RSVP Now",
  "recipientName": "John Doe",
  "company": {
    "name": "My Company",
    "logoUrl": "https://mycompany.com/logo.png",
    "primaryColor": "#f97316"
  },
  "from": "events@mycompany.com"
}
```

**Required Fields:**
- `to` - Recipient email address
- `eventName` - Name of the event (1-200 characters)
- `dateTime` - Event date and time
- `location` - Event location (1-500 characters)
- `ctaUrl` - RSVP/registration URL
- `company.name` - Company name (1-100 characters)

**Optional Fields:**
- `ctaLabel` - Button text (default: "RSVP Now")
- `recipientName` - Recipient's name for personalization
- `company.logoUrl` - Company logo URL
- `company.primaryColor` - Brand color (hex format)
- `from` - Custom from email (must be verified domain)

**Success Response (200):**
```json
{
  "success": true,
  "messageId": "abc123def456",
  "duration": "245ms"
}
```

---

### Send Payment Request
Send payment request emails with payment buttons or bank transfer details.

```http
POST /api/emails/payment-request
```

**Request Body:**
```json
{
  "to": "customer@example.com",
  "amount": 150.00,
  "currency": "USD",
  "description": "Monthly subscription fee",
  "dueDate": "March 31, 2026",
  "company": {
    "name": "My Company",
    "logoUrl": "https://mycompany.com/logo.png",
    "paymentLink": "https://myapp.com/pay/123",
    "bankDetails": {
      "bankName": "Example Bank",
      "accountName": "My Company Ltd",
      "accountNumber": "123456789",
      "iban": "GB29 NWBK 6016 1331 9268 19"
    }
  },
  "from": "billing@mycompany.com"
}
```

**Required Fields:**
- `to` - Recipient email address
- `amount` - Payment amount (positive number, max 1,000,000)
- `currency` - Currency code (USD, EUR, GBP, CAD, AUD)
- `description` - Payment description (1-500 characters)
- `dueDate` - Payment due date
- `company.name` - Company name

**Optional Fields:**
- `company.logoUrl` - Company logo URL
- `company.paymentLink` - Payment URL (shows "Pay Now" button)
- `company.bankDetails` - Bank transfer information
- `from` - Custom from email

**Success Response (200):**
```json
{
  "success": true,
  "messageId": "def456ghi789",
  "duration": "312ms"
}
```

---

### Send Password Reset
Send password reset emails with secure reset links.

```http
POST /api/emails/password-reset
```

**Request Body:**
```json
{
  "to": "user@example.com",
  "resetLink": "https://myapp.com/reset?token=secure-token-123",
  "recipientName": "John Doe",
  "company": {
    "name": "My Company",
    "logoUrl": "https://mycompany.com/logo.png",
    "primaryColor": "#f97316"
  },
  "from": "security@mycompany.com"
}
```

**Required Fields:**
- `to` - Recipient email address
- `resetLink` - Password reset URL
- `company.name` - Company name

**Optional Fields:**
- `recipientName` - Recipient's name for personalization
- `company.logoUrl` - Company logo URL
- `company.primaryColor` - Brand color
- `from` - Custom from email

**Success Response (200):**
```json
{
  "success": true,
  "messageId": "ghi789jkl012",
  "duration": "198ms"
}
```

---

## Error Responses

### Validation Error (400)
```json
{
  "success": false,
  "error": "Validation error: to: Invalid email address",
  "code": "VALIDATION_ERROR"
}
```

### Rate Limit Error (429)
```json
{
  "error": "Too many email requests, please try again later",
  "retryAfter": 900
}
```

### Service Error (503)
```json
{
  "success": false,
  "error": "Email service temporarily unavailable",
  "code": "SERVICE_UNAVAILABLE"
}
```

### Internal Error (500)
```json
{
  "success": false,
  "error": "Internal server error",
  "code": "INTERNAL_ERROR"
}
```

---

## Error Codes

| Code | Description | Action |
|------|-------------|--------|
| `VALIDATION_ERROR` | Invalid input data | Fix request format and retry |
| `RESEND_ERROR` | Resend API issue | Check API key and domain verification |
| `RATE_LIMIT_ERROR` | Too many requests | Wait and retry after specified time |
| `SERVICE_UNAVAILABLE` | Email service down | Retry later or check service status |
| `INTERNAL_ERROR` | Server error | Contact support if persistent |

---

## Examples

### cURL Examples

**Send Invitation:**
```bash
curl -X POST http://localhost:3001/api/emails/invitation \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "eventName": "Team Meeting",
    "dateTime": "Tomorrow at 10 AM",
    "location": "Conference Room B",
    "ctaUrl": "https://calendar.app/meeting/123",
    "company": {
      "name": "Acme Corp"
    }
  }'
```

**Send Payment Request:**
```bash
curl -X POST http://localhost:3001/api/emails/payment-request \
  -H "Content-Type: application/json" \
  -d '{
    "to": "customer@example.com",
    "amount": 99.99,
    "currency": "USD",
    "description": "Premium subscription",
    "dueDate": "End of month",
    "company": {
      "name": "Acme Corp",
      "paymentLink": "https://pay.acme.com/invoice/456"
    }
  }'
```

### JavaScript Examples

**Using Fetch:**
```javascript
const response = await fetch('http://localhost:3001/api/emails/invitation', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    to: 'user@example.com',
    eventName: 'Product Demo',
    dateTime: 'Next Friday at 3 PM',
    location: 'Online via Zoom',
    ctaUrl: 'https://zoom.us/meeting/123',
    company: {
      name: 'My Startup',
      logoUrl: 'https://mystartup.com/logo.png'
    }
  })
});

const result = await response.json();
console.log(result);
```

**Using Axios:**
```javascript
const axios = require('axios');

try {
  const response = await axios.post('http://localhost:3001/api/emails/payment-request', {
    to: 'customer@example.com',
    amount: 250.00,
    currency: 'EUR',
    description: 'Consulting services',
    dueDate: '30 days',
    company: {
      name: 'Consulting Co',
      bankDetails: {
        bankName: 'European Bank',
        accountName: 'Consulting Co Ltd',
        iban: 'DE89 3704 0044 0532 0130 00'
      }
    }
  });
  
  console.log('Email sent:', response.data.messageId);
} catch (error) {
  console.error('Error:', error.response.data);
}
```

---

## Best Practices

1. **Always validate input** on your side before sending
2. **Handle rate limits** with exponential backoff
3. **Store message IDs** for tracking and debugging
4. **Use verified domains** for from addresses
5. **Monitor error rates** and adjust accordingly
6. **Test thoroughly** in development before production