Subscribe readers, list subscribers, and manage newsletter issues via the MisarBlog API.

Overview

MisarBlog includes a built-in newsletter system for creators. Readers can subscribe to a creator's newsletter, and creators can view subscribers, export lists, and send issues from the dashboard.

Subscribe to a Newsletter

POST api.misar.io/blog/newsletter/subscribe

Subscribes an email address to a creator's newsletter. A verification email is sent — the subscription is pending until the reader confirms.

This endpoint is public — no API key required. Suitable for embedding a subscribe form on your own site.

This endpoint is rate-limited to 3 requests per 5 minutes per IP to prevent abuse.

Request Body

{
  "newsletter_id": "uuid-of-the-newsletter",
  "email": "[email protected]"
}

newsletter_idstringrequired

The UUID of the creator's newsletter. Find it in your dashboard at misar.blog/dashboard/newsletter.

emailstringrequired

The reader's email address.

Response

200 OK — subscription created, verification email sent.

{ "success": true }

400 Bad Request — missing or invalid fields.

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

Example

const res = await fetch("https://api.misar.io/blog/newsletter/subscribe", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    newsletter_id: "your-newsletter-uuid",
    email: "[email protected]",
  }),
});
const data = await res.json();
if (data.success) {
  console.log("Check your inbox to confirm!");
}

Unsubscribe

POST api.misar.io/blog/email/unsubscribe

Unsubscribes an email from a newsletter using the signed token included in every outgoing email's unsubscribe link. No authentication required.

Request Body

{
  "token": "signed-unsubscribe-token"
}

tokenstringrequired

Signed unsubscribe token extracted from the ?token= query parameter in the email's unsubscribe link.

Response

200 OK — subscription cancelled.

List Subscribers

GET api.misar.io/blog/newsletter/subscribers

Returns the authenticated creator's subscriber list. API key required.

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	50	Results per page (max 200)
`offset`	integer	0	Pagination offset
`status`	string	—	Filter by status: `pending`, `active`, `unsubscribed`, `bounced`
`export`	boolean	—	Set `true` to download a CSV file instead of JSON

Response (JSON)

200 OK

{
  "subscribers": [
    {
      "email": "[email protected]",
      "subscribed_at": "2026-03-10T08:00:00Z",
      "status": "active"
    }
  ],
  "total": 1240,
  "limit": 50,
  "offset": 0
}

subscribersarray

Array of subscriber objects.

totalnumber

Total number of subscribers matching the current status filter.

Response (CSV Export)

When ?export=true, the response is a downloadable CSV file with Content-Type: text/csv:

Content-Disposition: attachment; filename=subscribers.csv

CSV exports are rate-limited to 3 exports per hour to prevent bulk exfiltration.

Example

# List active subscribers
curl "https://api.misar.io/blog/newsletter/subscribers?status=active&limit=100" \
  -H "Authorization: Bearer mbk_your_api_key"

# Export all as CSV
curl "https://api.misar.io/blog/newsletter/subscribers?export=true" \
  -H "Authorization: Bearer mbk_your_api_key" \
  -o subscribers.csv

List Newsletter Issues

GET api.misar.io/blog/newsletter/issues

Returns the authenticated creator's sent newsletter issues. API key required.

Response

200 OK

{
  "issues": [
    {
      "id": "uuid",
      "subject": "Weekly Digest #12",
      "sent_at": "2026-04-14T09:00:00Z",
      "recipient_count": 984,
      "open_rate": 0.41
    }
  ]
}

issuesarray

Array of sent newsletter issues, ordered by sent_at descending.

open_ratenumber

Open rate as a decimal (0–1). 0.41 = 41%.

Example

curl "https://api.misar.io/blog/newsletter/issues" \
  -H "Authorization: Bearer mbk_your_api_key"