ifies the operation to perform. Currently supports stats to retrieve subscription counts. |

Request Body (POST only)

The POST method expects a JSON payload containing the subscriber's email address.

Field	Type	Required	Validation Rules
email	string	Yes	Must be a valid string containing at least one @ character.

Example Request Body:

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

Response Format

All responses return JSON. Status codes and payload structures vary based on the HTTP method and execution outcome.

Success Responses (200 OK)

POST: New Subscription

{
  "message": "Subscribed successfully",
  "data": {
    "id": "uuid-string",
    "email": "developer@example.com",
    "status": "active",
    "subscribedAt": "2024-06-15T10:30:00.000Z"
  }
}

POST: Duplicate Email

{
  "message": "Already subscribed"
}

GET: Subscription Statistics

{
  "total": 1245,
  "active": 1198
}

Error Responses

Status Code	Condition	Response Example
400	Invalid email format (missing @) or missing/unsupported action parameter	{"error": "Invalid email address"} or {"error": "Invalid action"}
500	Database connection failure, Supabase query error, or unexpected server exception	{"error": "Failed to subscribe"} or {"error": "<runtime error message>"}

Note: The endpoint does not return 401 or 404 status codes. Authentication is not enforced, and the path is statically routed.

Usage Example

Subscribe a New Email (POST)

curl -X POST https://api.codcompass.com/api/newsletter/subscribe \
  -H "Content-Type: application/json" \
  -d '{"email": "jane.doe@company.com"}'

Retrieve Subscription Statistics (GET)

curl -X GET "https://api.codcompass.com/api/newsletter/subscribe?action=stats"

JavaScript Fetch Example

// Subscribe
const subscribe = async (email) => {
  const res = await fetch('/api/newsletter/subscribe', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ email }),
  });
  return res.json();
};

// Fetch Stats
const getStats = async () => {
  const res = await fetch('/api/newsletter/subscribe?action=stats');
  return res.json();
};

Common Pitfalls

1. Duplicate Handling Returns 200, Not 4xx
   The endpoint intentionally returns a 200 OK status when an email is already registered, accompanied by a {"message": "Already subscribed"} payload. Frontend logic must parse the response body rather than relying on HTTP status codes to detect duplicates. Failing to do so may trigger false error states in your UI.

2. Minimal Email Validation
   Server-side validation only checks for the presence of an @ character. It does not verify domain existence, RFC compliance, or disposable email patterns. Implement robust client-side validation (e.g., regex or third-party validation libraries) before making the network request to reduce unnecessary API calls and database load.

3. Public Exposure & Abuse Prevention
   Because the endpoint requires no authentication, it is vulnerable to automated spam submissions. Always pair this endpoint with client-side rate limiting, CAPTCHA challenges, or honeypot fields. Additionally, ensure the Supabase service role key used in the backend is strictly confined to server-side execution (Next.js API routes) and never leaked to client bundles.

Related Endpoints

While /api/newsletter/subscribe handles opt-in registration and metric aggregation, it typically operates alongside complementary endpoints within the codcompass.com API ecosystem:

• /api/newsletter/unsubscribe — Manages opt-out requests and updates subscriber status to inactive or removes records based on platform retention policies.
• /api/users/profile — Links newsletter preferences to authenticated user accounts, enabling personalized communication settings and cross-device sync.
• /api/analytics/events — Tracks engagement metrics such as email opens, click-through rates, and campaign performance, which can be correlated with subscription data for lifecycle analysis.

These endpoints share consistent response formatting, error handling patterns, and authentication models. When building integrated workflows, ensure your application respects rate limits, handles pagination where applicable, and caches statistical responses to minimize redundant database queries.