Email APIs

Endpoints for managing newsletters, composing custom emails, managing email templates, and subscriber lists.

Base URL: https://ycwadelaide.adenmgb.com

Authentication: All endpoints require Authorization: Bearer <token> header.

Quick Links

• Newsletters API - Create and send newsletters
• Compose Emails API - Send custom emails
• Email Templates API - Manage reusable templates
• Subscribers API - Manage subscriber list

Newsletters API

GET /api/staff/newsletters

Retrieve all newsletters (draft, scheduled, and sent).

Response:

[
  {
    "id": 1,
    "title": "December 2024 Newsletter",
    "subject": "YCW Adelaide December Update",
    "html_content": "<p>Newsletter content...</p>",
    "text_content": "Newsletter content...",
    "status": "sent",
    "scheduled_send_at": null,
    "sent_at": "2024-12-01T10:00:00.000Z",
    "approvalStatus": "approved"
  }
]

Notes:

• Results ordered by created_at DESC
• status can be: "draft", "scheduled", or "sent"
• Sent newsletters cannot be edited
• Approval workflow applies (see Approval APIs)

POST /api/staff/newsletters

Create a new newsletter.

Request Body:

{
  "title": "New Newsletter",
  "subject": "Newsletter Subject Line",
  "html_content": "<p>Newsletter HTML content...</p>",
  "text_content": "Newsletter plain text content...",
  "scheduled_send_at": null,
  "notes": "Optional notes"
}

Important: All new newsletters are created as draft. Sending requires approval workflow.

PUT /api/staff/newsletters/:id

Update an existing newsletter (draft or scheduled only).

Request Body: (Same as POST, all fields optional)

Note: Sent newsletters cannot be edited.

POST /api/staff/newsletters/:id/send

Send a newsletter immediately to all active subscribers.

Success Response:

{
  "success": true,
  "sentTo": 150
}

Notes:

• Newsletter must be approved before sending
• Sends to all subscribers with status: "subscribed"
• Newsletter status changes to "sent"

POST /api/staff/newsletters/:id/schedule

Schedule a newsletter for future sending.

Request Body:

{
  "scheduled_send_at": "2025-02-01T10:00:00.000Z"
}

Notes:

• Newsletter must be approved before scheduling
• Newsletter status changes to "scheduled"
• Sends automatically at scheduled time

Compose Emails API

GET /api/staff/compose-emails

Retrieve all compose emails (draft, scheduled, and sent).

Response:

[
  {
    "id": 1,
    "title": "Event Invitation",
    "subject": "You're Invited to Our Event",
    "html_content": "<p>Hello,</p><p>You're invited...</p>",
    "recipient_emails": ["user1@example.com", "user2@example.com"],
    "status": "sent",
    "sent_at": "2024-12-01T10:00:00.000Z"
  }
]

Notes:

• Results ordered by created_at DESC
• recipient_emails is an array of email addresses
• Sent emails cannot be edited

POST /api/staff/compose-emails

Create a new compose email.

Request Body:

{
  "title": "Email Title",
  "subject": "Email Subject Line",
  "html_content": "<p>Email HTML content...</p>",
  "text_content": "Email plain text content...",
  "recipient_emails": ["user1@example.com", "user2@example.com"],
  "scheduled_send_at": null
}

Required Fields:

• subject - Email subject line
• html_content - HTML email content
• recipient_emails - Array of at least one email address

POST /api/staff/compose-emails/:id/send

Send a compose email immediately.

Success Response:

{
  "success": true
}

Notes:

• Sends to all emails in recipient_emails array
• Email status changes to "sent"

Email Templates API

GET /api/staff/email-templates

Retrieve all email templates, optionally filtered by category.

Query Parameters:

• category (optional) - Filter by category (e.g., "newsletter", "invite")

Response:

[
  {
    "id": 1,
    "name": "Monthly Newsletter Template",
    "subject": "YCW Adelaide {{month}} Newsletter",
    "html_content": "<p>Hello {{name}},</p><p>{{content}}</p>",
    "text_content": "Hello {{name}},\n\n{{content}}",
    "category": "newsletter",
    "variables": "name,content,month"
  }
]

Notes:

• Results ordered by created_at DESC
• variables is comma-separated list of available template variables
• Use {{variable}} syntax in templates

POST /api/staff/email-templates

Create a new email template.

Request Body:

{
  "name": "Template Name",
  "subject": "Email Subject {{variable}}",
  "html_content": "<p>Template HTML with {{variables}}</p>",
  "text_content": "Template text with {{variables}}",
  "category": "newsletter",
  "html_wrapper": "<html><body>{{content}}</body></html>"
}

Template Variables:

• Use {{variable}} syntax
• Variables are replaced when template is used
• Common variables: {{name}}, {{email}}, {{content}}, {{unsubscribe}}

PUT /api/staff/email-templates/:id

Update an existing template.

Request Body: (Same as POST, all fields optional)

DELETE /api/staff/email-templates/:id

Delete an email template.

Subscribers API

GET /api/staff/newsletter-subscribers

Retrieve all newsletter subscribers, optionally filtered by status.

Query Parameters:

• status (optional) - Filter by status: "subscribed" or "unsubscribed"

Response:

[
  {
    "id": 1,
    "email": "subscriber@example.com",
    "name": "John Doe",
    "status": "subscribed",
    "source": "website",
    "createdAt": "2024-01-15T10:00:00.000Z"
  }
]

Notes:

• Results ordered by created_at DESC
• name is optional
• source indicates where subscription came from

POST /api/staff/newsletter-subscribers

Add a new subscriber.

Request Body:

{
  "email": "newsubscriber@example.com",
  "name": "New Subscriber",
  "source": "manual"
}

Required Fields:

• email - Valid email address

Notes:

• Email must be unique
• If email already exists, returns existing subscriber
• Default status is "subscribed"

PUT /api/staff/newsletter-subscribers/:id

Update subscriber information.

Request Body:

{
  "name": "Updated Name",
  "status": "subscribed"
}

Notes:

• Can update name and status
• Setting status: "unsubscribed" sets unsubscribedAt timestamp

DELETE /api/staff/newsletter-subscribers/:id

Delete a subscriber.

Notes:

• This action cannot be undone
• Consider unsubscribing instead of deleting

Public Endpoints

POST /api/newsletter/subscribe

Public endpoint to subscribe to newsletter (no authentication required).

Request Body:

{
  "email": "subscriber@example.com",
  "name": "Subscriber Name"
}

Success Response:

{
  "success": true,
  "message": "Successfully subscribed"
}

POST /api/newsletter/unsubscribe

Public endpoint to unsubscribe from newsletter.

Request Body:

{
  "email": "subscriber@example.com"
}

Success Response:

{
  "success": true,
  "message": "Successfully unsubscribed"
}

Related Guides

• Approval APIs - Newsletter approval workflow
• Public APIs - Public newsletter endpoints