Newsletter

Subscribe email addresses to your newsletter lists. Successful requests create a subscription record with support for multiple lists, tracking metadata, and idempotent operations.

Subscribers are organized by lists and can be managed through your dashboard. Lists are automatically created when referenced.

POST/api/newsletter/subscribe

Subscribe an email address to a newsletter list.

Headers

Content-Type: application/json (required)
x-api-key: <YOUR_API_KEY> (required)

Body

Name
email
Type
string
Description
Required. Valid email address to subscribe.
Name
list
Type
string
Description
Optional list identifier (e.g., "product-updates", "weekly-digest"). If not provided, subscribes to the default list. Lists are auto-created if they don't exist.
Name
source
Type
string
Description
Optional source identifier (e.g., "website", "landing_page", "mobile_app") for tracking where the subscription originated.
Name
metadata
Type
object
Description
Optional object for tracking data like UTM parameters, page URLs, custom fields, etc. Arbitrary keys are accepted and stored with the subscription.

Idempotent behavior: Submitting the same email to the same list multiple times won't create duplicates. Existing subscriptions will be updated with new metadata.

Multi-list support: The same email can subscribe to multiple lists independently. Each list subscription is tracked separately.

Request

POST

/api/newsletter/subscribe

curl https://api.webrocket.app/api/newsletter/subscribe \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "email": "user@example.com",
    "list": "product-updates",
    "source": "website_footer",
    "metadata": {
      "utm_source": "google",
      "utm_medium": "cpc",
      "utm_campaign": "newsletter_signup_2025",
      "page_url": "https://example.com/signup",
      "referrer": "https://google.com/search"
    }
  }'

Response (200)

{
  "success": true,
  "data": {
    "id": 123,
    "email": "user@example.com",
    "list": "product-updates",
    "status": "active",
    "wasNewlyCreated": true,
    "subscribedAt": "2025-01-15T10:30:00Z"
  },
  "message": "Successfully subscribed to newsletter"
}

Response (existing subscriber)

{
  "success": true,
  "data": {
    "id": 123,
    "email": "user@example.com",
    "list": "product-updates", 
    "status": "active",
    "wasNewlyCreated": false,
    "subscribedAt": "2025-01-10T08:15:00Z"
  },
  "message": "Subscription updated successfully"
}

Error (400/401/500)

{
  "success": false,
  "error": "Invalid email format"
}

Response Fields

Name
success
Type
boolean
Description
Always true for successful requests.
Name
data.id
Type
number
Description
Unique subscription identifier.
Name
data.email
Type
string
Description
The subscribed email address.
Name
data.list
Type
string
Description
List identifier. Shows "default" if no specific list was provided.
Name
data.status
Type
string
Description
Current subscription status. Always "active" for new subscriptions.
Name
data.wasNewlyCreated
Type
boolean
Description
true if this is a new subscription, false if an existing subscription was updated.
Name
data.subscribedAt
Type
string
Description
ISO timestamp of when the email was first subscribed to this list.
Name
message
Type
string
Description
Human-readable success message.

Common Error Responses

Name
401 Unauthorized
Description
Invalid API key - Check that your API key is correct and active.
Name
400 Bad Request
Description
Missing required field: email - The email parameter is required.
Name
400 Bad Request
Description
Invalid email format - The provided email address is not valid.
Name
500 Internal Server Error
Description
Server error - Something went wrong on our end. Please try again.

Error Response Format

{
  "success": false,
  "error": "Invalid email format"
}

Advanced Usage

Multiple List Subscriptions

// Subscribe to multiple lists
const lists = ['newsletter', 'product-updates', 'special-offers'];

const subscriptions = await Promise.all(
  lists.map(list => 
    fetch('/api/newsletter/subscribe', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': 'YOUR_API_KEY'
      },
      body: JSON.stringify({
        email: 'user@example.com',
        list: list,
        source: 'preference_center'
      })
    }).then(r => r.json())
  )
);

UTM Parameter Tracking

// Automatically capture UTM parameters
function getUTMParameters() {
  const params = new URLSearchParams(window.location.search);
  return {
    utm_source: params.get('utm_source'),
    utm_medium: params.get('utm_medium'),
    utm_campaign: params.get('utm_campaign'),
    utm_term: params.get('utm_term'),
    utm_content: params.get('utm_content')
  };
}

// Subscribe with UTM tracking
const subscribeWithTracking = async (email) => {
  const metadata = {
    ...getUTMParameters(),
    page_url: window.location.href,
    referrer: document.referrer,
    timestamp: new Date().toISOString()
  };

  return fetch('/api/newsletter/subscribe', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'YOUR_API_KEY'
    },
    body: JSON.stringify({
      email,
      list: 'main-newsletter',
      source: 'website',
      metadata
    })
  }).then(r => r.json());
};

Key Features

Idempotent Operations - Safe to retry requests. Duplicate subscriptions to the same list are automatically handled by updating the existing record.

Auto-Created Lists - Reference any list name in the list parameter. If it doesn't exist, it will be automatically created with a friendly name.

Multi-Tenant Isolation - Each API key is scoped to your account. Subscriber data is completely isolated between accounts.

Rich Metadata - Store UTM parameters, page URLs, custom tracking data, or any other information you need with each subscription.

Subscribe to newsletter