Enable paid newsletter subscriptions, sponsor placements, and tip jars for your audience

MisarMail supports three monetization models for newsletter creators:

Model	Description	Auth
Sponsors	Sell ad placements in your emails (header, footer, inline)	Session
Paid subscriptions	Charge readers for access to premium newsletters	Session
Tip jar	Accept one-time tips from readers	API key (`monetization` or `send` scope)

All amounts are in the smallest currency unit (cents for USD/EUR/GBP).

List Sponsor Slots

GET/mail/v1/monetization/sponsors

Returns all active and upcoming sponsor placements for your account.

Response fields

sponsorsArray<Sponsor>

Sponsor placements. Each includes id, sponsor_name, logo_url, target_url, position ("header", "footer", or "inline"), active_from, and active_until.

curl https://api.misar.io/mail/v1/monetization/sponsors \
  -H "Authorization: Bearer msk_..."

[
  {
    "id": "spon_01j9xkz3p",
    "sponsor_name": "Acme Corp",
    "logo_url": "https://cdn.example.com/acme-logo.png",
    "target_url": "https://acme.example.com",
    "position": "header",
    "active_from": "2025-12-01T00:00:00Z",
    "active_until": "2025-12-31T23:59:59Z"
  }
]

Create a Sponsor Slot

POST/mail/v1/monetization/sponsors

Creates a new sponsor placement. Requires the monetization scope on your API key.

Request body

sponsor_namestringbodyrequired

Display name of the sponsor.

logo_urlstringbodyrequired

HTTPS URL to sponsor logo.

target_urlstringbodyrequired

Click-through URL.

positionstringbodyrequired

header, footer, or inline.

active_fromISO 8601bodyrequired

Placement start date.

active_untilISO 8601bodyrequired

Placement end date.

price_centsintegerbody

Amount paid by sponsor (for records).

currencystringbodydefault: USD

ISO 4217 currency code.

Response fields

successboolean

true when the sponsor slot was created.

dataobject

The created sponsor slot, including id, sponsor_name, position, active_from, and active_until.

{
  "sponsor_name": "Acme Corp",
  "logo_url": "https://cdn.example.com/acme-logo.png",
  "target_url": "https://acme.example.com",
  "position": "header",
  "active_from": "2025-12-01T00:00:00Z",
  "active_until": "2025-12-31T23:59:59Z",
  "price_cents": 29900,
  "currency": "USD"
}

{
  "success": true,
  "data": {
    "id": "spon_01j9xkz3p",
    "sponsor_name": "Acme Corp",
    "position": "header",
    "active_from": "2025-12-01T00:00:00Z",
    "active_until": "2025-12-31T23:59:59Z"
  }
}

List Subscriptions

GET/mail/v1/monetization/subscriptions

Returns all paid newsletter subscriber records for your account. Requires session auth.

Response fields

subscriptionsArray<Subscription>

Subscriber records. Each includes id, subscriber_email, plan, amount_cents, currency, status ("active", "cancelled", or "past_due"), and created_at.

curl https://api.misar.io/mail/v1/monetization/subscriptions \
  -H "Cookie: session=..."

[
  {
    "id": "sub_01j8abc12",
    "subscriber_email": "[email protected]",
    "plan": "monthly",
    "amount_cents": 799,
    "currency": "USD",
    "status": "active",
    "created_at": "2025-10-15T08:30:00Z"
  }
]

Create a Subscription Record

POST/mail/v1/monetization/subscriptions

Records a new paid subscriber. Typically called from your Stripe webhook handler after a successful payment. Requires the monetization scope.

Request body

subscriber_emailstringbodyrequired

Subscriber's email address.

planstringbodyrequired

Your plan identifier (e.g. monthly, annual).

amount_centsintegerbodyrequired

Recurring charge amount in cents.

currencystringbodyrequired

ISO 4217 currency code.

stripe_subscription_idstringbody

Stripe subscription ID for reconciliation.

Response fields

successboolean

true when the subscription record was created.

dataobject

The created record, including id, subscriber_email, plan, and status.

{
  "subscriber_email": "[email protected]",
  "plan": "monthly",
  "amount_cents": 799,
  "currency": "USD",
  "stripe_subscription_id": "sub_1OaBcDeFgHiJkL"
}

{
  "success": true,
  "data": {
    "id": "sub_01j8abc12",
    "subscriber_email": "[email protected]",
    "plan": "monthly",
    "status": "active"
  }
}

Record a Tip

POST/mail/v1/monetization/tip

Records a reader tip and calculates the platform fee. The tip endpoint accepts an API key with the monetization or send:transactional scope.

Request body

amount_centsintegerbodyrequired

Tip amount in cents. Min: 50 (¢50). Max: 100000 ($1,000).

currencystringbodydefault: USD

ISO 4217 code.

emailstringbody

Tipper's email address.

namestringbody

Tipper's display name.

messagestringbody

Optional message, max 500 characters.

stripe_payment_idstringbody

Stripe payment intent ID for reconciliation.

Response fields

successboolean

true when the tip was recorded.

tip_idstring

ID of the recorded tip.

gross_amount_centsinteger

Tip amount before fees.

platform_fee_centsinteger

Platform fee deducted.

net_amount_centsinteger

Amount after the platform fee.

timestampstring

ISO-8601 time the tip was recorded.

curl -X POST https://api.misar.io/mail/v1/monetization/tip \
  -H "Authorization: Bearer msk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "Alex",
    "amount_cents": 500,
    "currency": "USD",
    "message": "Great newsletter!"
  }'

{
  "success": true,
  "tip_id": "tip_01j7xyz99",
  "gross_amount_cents": 500,
  "platform_fee_cents": 25,
  "net_amount_cents": 475,
  "timestamp": "2025-11-20T16:45:00Z"
}

Platform fees are calculated server-side and deducted from payouts. The fee percentage is based on your current plan — higher-tier plans have lower fees. Check your dashboard for the exact rate.

Required Scopes

Endpoint	Required scope
`GET /v1/monetization/sponsors`	Session
`POST /v1/monetization/sponsors`	Session + `monetization`
`GET /v1/monetization/subscriptions`	Session
`POST /v1/monetization/subscriptions`	Session + `monetization`
`POST /v1/monetization/tip`	API key: `monetization` or `send:transactional`

Monetization

List Sponsor Slots

Create a Sponsor Slot

List Subscriptions

Create a Subscription Record

Record a Tip

Required Scopes