Subscribers API

Add, update, and manage newsletter subscribers programmatically.

Endpoints

Method	Endpoint	Description
GET	/subscriptions	List all subscribers
GET	/subscriptions/:id	Get a subscriber
POST	/subscriptions	Create a subscriber
PATCH	/subscriptions/:id	Update a subscriber
DELETE	/subscriptions/:id	Delete a subscriber
POST	/subscriptions/:id/add_tag	Add a tag
DELETE	/subscriptions/:id/remove_tag	Remove a tag
POST	/subscriptions/bulk_create	Bulk import subscribers

---

List Subscribers

GET /api/v1/subscriptions

Parameters

Parameter	Type	Description
page	integer	Page number (default: 1)
per_page	integer	Results per page (default: 25, max: 100)
status	string	Filter by status: active, unsubscribed, bounced
tag	string	Filter by tag
q	string	Search by email or name

Response

{
  "data": [
    {
      "id": 1,
      "email": "[email protected]",
      "name": "John Doe",
      "status": "active",
      "tags": ["vip", "tech"],
      "subscribed_at": "2025-01-01T12:00:00Z",
      "created_at": "2025-01-01T12:00:00Z"
    }
  ],
  "meta": {
    "total": 1500,
    "page": 1,
    "per_page": 25,
    "total_pages": 60
  }
}

---

Get Subscriber

GET /api/v1/subscriptions/:id

Response

{
  "data": {
    "id": 1,
    "email": "[email protected]",
    "name": "John Doe",
    "status": "active",
    "tags": ["vip", "tech"],
    "subscribed_at": "2025-01-01T12:00:00Z",
    "unsubscribed_at": null,
    "referral_code": "abc123",
    "referral_count": 5,
    "created_at": "2025-01-01T12:00:00Z",
    "updated_at": "2025-01-10T12:00:00Z"
  }
}

---

Create Subscriber

POST /api/v1/subscriptions

Request Body

{
  "email": "[email protected]",
  "name": "Jane Smith",
  "tags": ["newsletter", "product-updates"]
}

Parameters

Parameter	Type	Required	Description
email	string	Yes	Subscriber email address
name	string	No	Subscriber name
tags	array	No	Array of tag strings

Response

{
  "data": {
    "id": 456,
    "email": "[email protected]",
    "name": "Jane Smith",
    "status": "active",
    "tags": ["newsletter", "product-updates"],
    "subscribed_at": "2025-01-10T12:00:00Z",
    "created_at": "2025-01-10T12:00:00Z"
  }
}

---

Update Subscriber

PATCH /api/v1/subscriptions/:id

Request Body

{
  "name": "Jane Wilson",
  "tags": ["vip", "newsletter"]
}

---

Delete Subscriber

DELETE /api/v1/subscriptions/:id

Response

HTTP/1.1 204 No Content

---

Add Tag

POST /api/v1/subscriptions/:id/add_tag

Request Body

{
  "tag": "vip"
}

---

Remove Tag

DELETE /api/v1/subscriptions/:id/remove_tag?tag=vip

---

Bulk Create

Import multiple subscribers at once:

POST /api/v1/subscriptions/bulk_create

Request Body

{
  "subscribers": [
    { "email": "[email protected]", "name": "User 1" },
    { "email": "[email protected]", "name": "User 2" },
    { "email": "[email protected]", "name": "User 3", "tags": ["vip"] }
  ]
}

Response

{
  "data": {
    "imported": 3,
    "skipped": 0,
    "errors": []
  }
}

Error Codes

Code	Description
duplicate_email	Email already exists
invalid_email	Email format is invalid
not_found	Subscriber not found