Subscribers API

Add, update, and manage newsletter subscribers programmatically.

Endpoints

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

---

List Subscribers

GET /api/v1/subscribers

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

Response

{
  "subscribers": [
    {
      "id": 1,
      "email": "[email protected]",
      "status": "active",
      "tags": ["vip", "tech"],
      "subscribed_at": "2025-01-01T12:00:00Z",
      "unsubscribed_at": null,
      "created_at": "2025-01-01T12:00:00Z",
      "updated_at": "2025-01-01T12:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "has_more": true
  }
}

---

Get Subscriber

GET /api/v1/subscribers/:id

Response

{
  "id": 1,
  "email": "[email protected]",
  "status": "active",
  "tags": ["vip", "tech"],
  "subscribed_at": "2025-01-01T12:00:00Z",
  "unsubscribed_at": null,
  "created_at": "2025-01-01T12:00:00Z",
  "updated_at": "2025-01-10T12:00:00Z"
}

---

Create Subscriber

POST /api/v1/subscribers

Request Body

{
  "email": "[email protected]"
}

Parameters

Parameter	Type	Required	Description
email	string	Yes	Subscriber email address

Response

{
  "id": 456,
  "email": "[email protected]",
  "status": "active",
  "tags": [],
  "subscribed_at": "2025-01-10T12:00:00Z",
  "unsubscribed_at": null,
  "created_at": "2025-01-10T12:00:00Z",
  "updated_at": "2025-01-10T12:00:00Z"
}

---

Update Subscriber

PATCH /api/v1/subscribers/:id

Request Body

{
  "subscriber": {
    "status": "unsubscribed"
  }
}

Parameters

Parameter	Type	Required	Description
subscriber[status]	string	No	Subscriber status: active, unsubscribed

---

Delete Subscriber

DELETE /api/v1/subscribers/:id

Response

HTTP/1.1 204 No Content

---

Add Tag

POST /api/v1/subscribers/:id/add_tag

Request Body

{
  "tag": "vip"
}

---

Remove Tag

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

---

Bulk Create

Import multiple subscribers at once:

POST /api/v1/subscribers/bulk_create

Request Body

{
  "subscribers": [
    { "email": "[email protected]" },
    { "email": "[email protected]" },
    { "email": "[email protected]" }
  ]
}

Response

{
  "created": 3,
  "existing": 0,
  "errors": []
}

Error Codes

Code	Description
invalid_email	Email format is invalid
not_found	Subscriber not found