Email APIs

Unified email sending and campaign management.

Simple Email API

Method: POST
URL: /api/send-simple-email
Description: Lightweight email API with inline styling - no company setup required
Quick link: Full documentation

The Simple Email API is perfect for quick, one-off emails without the complexity of company setup or database configuration.

Simple Email Request

{
  "to": ["user@example.com"],
  "title": "Welcome!",
  "description": "Thank you for signing up.",
  "theme": "blue",
  "logoUrl": "https://example.com/logo.png",
  "pdf": ["https://example.com/guide.pdf"]
}

Features: 4 themes (blue, red, black, stone), multiple recipients, PDF attachments, custom branding

Preview: See themes in action

Send Email

Method: POST
URL: /api/send-email
Description: Single endpoint to send different email templates with optional attachments.
Supported templates: order, promotional, otp, welcome, newsletter, simple.
Quick links: Preview templates, Database diagram

Request body (generic)

{
  "template": "order",
  "payload": {
    "to": "customer@example.com",
    "subject": "Optional custom subject",
    "branding": { "siteName": "Your Site", "siteUrl": "https://your.site" },
    "attachments": [
      { "s3": { "bucket": "audla", "key": "path/file.pdf", "filename": "invoice.pdf", "contentType": "application/pdf" } },
      { "filename": "terms.txt", "contentBase64": "YmFzZTY0IQ==", "contentType": "text/plain" }
    ]
  }
}

Order fields:

{
  "order": { "id": "A-123", "date": "2025-01-01", "status": "paid" },
  "customer": { "name": "Jane Doe", "email": "customer@example.com" },
  "shipping": { "name": "Jane Doe", "address1": "123 St", "city": "Montreal", "province": "QC", "postalCode": "H1H 1H1", "country": "Canada" },
  "items": [{ "name": "Item", "quantity": 1, "price": "$10.00", "imageUrl": "https://..." }],
  "summary": { "subtotal": "$10.00", "tax": "$1.00", "shipping": "$0.00", "total": "$11.00" },
  "tax": { "tps": "123", "tvq": "456" },
  "pdf": { "bucket": "audla", "key": "Invoicing/2025/08/AUDLA_...pdf", "filename": "invoice.pdf" }
}

Promotional fields:

{
  "recipient": { "email": "user@example.com", "name": "User" },
  "site": { "subject": "Newsletter" },
  "featuredProducts": [{ "name": "Product", "url": "https://..." }],
  "events": [{ "title": "Event", "date": "2025-01-01" }],
  "campaignId": "abc-123"
}

OTP fields:

{
  "recipient": { "email": "user@example.com" },
  "otp": "123456",
  "expiresIn": "10 minutes",
  "branding": { "siteName": "Your Site", "siteUrl": "https://your.site" }
}

Welcome fields:

{
  "recipient": { "email": "user@example.com", "name": "Jane" },
  "features": [{ "title": "Profile", "description": "Complete your profile" }],
  "branding": { "siteName": "Your Site", "siteUrl": "https://your.site" }
}

Newsletter fields:

{
  "recipient": { "email": "user@example.com" },
  "featuredImage": "https://.../image.png",
  "articles": [{ "title": "Post", "excerpt": "...", "url": "#" }],
  "branding": { "siteName": "Your Site", "siteUrl": "https://your.site" }
}

Campaigns

Create Campaign

Method: POST
URL: /api/campaigns/create
Description: Creates a campaign payload and unsubscribe tokens. Persists to DB only if companyId, templateId, and createdBy are provided.

{
  "name": "Q1 Newsletter",
  "description": "Quarterly updates",
  "companyId": "company-1",
  "templateId": "template-1",
  "createdBy": "user-1",
  "recipients": [{ "email": "user@example.com", "name": "User" }]
}

{
  "success": true,
  "campaignId": "...",
  "recipients": 1,
  "persisted": true
}

Send Campaign

Method: POST
URL: /api/campaigns/[campaignId]/send
Description: Publishes recipient emails to QStash. If no recipients provided in body and DB is configured, loads from DB.

{
  "recipients": [{ "email": "user@example.com", "name": "User" }],
  "site": { "subject": "Hello" },
  "branding": { "siteName": "Your Site" }
}

Unsubscribe

Unsubscribe Endpoint

Method: GET
URL: /api/campaigns/unsubscribe?email=...&campaignId=...&token=...
Description: Validates token and records unsubscription if DB is configured.

Token generation

sha256_hmac(secret, email + '|' + campaignId)