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.

GET /health

Response:

{
  "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.

GET /api

Response:

{
  "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.

POST /api/emails/invitation

Request Body:

{
  "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):

{
  "success": true,
  "messageId": "abc123def456",
  "duration": "245ms"
}

---

Send Payment Request

Send payment request emails with payment buttons or bank transfer details.

POST /api/emails/payment-request

Request Body:

{
  "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):

{
  "success": true,
  "messageId": "def456ghi789",
  "duration": "312ms"
}

---

Send Password Reset

Send password reset emails with secure reset links.

POST /api/emails/password-reset

Request Body:

{
  "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):

{
  "success": true,
  "messageId": "ghi789jkl012",
  "duration": "198ms"
}

---

Error Responses

Validation Error (400)

{
  "success": false,
  "error": "Validation error: to: Invalid email address",
  "code": "VALIDATION_ERROR"
}

Rate Limit Error (429)

{
  "error": "Too many email requests, please try again later",
  "retryAfter": 900
}

Service Error (503)

{
  "success": false,
  "error": "Email service temporarily unavailable",
  "code": "SERVICE_UNAVAILABLE"
}

Internal Error (500)

{
  "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:

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:

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:

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:

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