Misar IO Docs
MisarMailApi Reference

Monetization

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

Overview

MisarMail supports three monetization models for newsletter creators:

ModelDescriptionAuth
SponsorsSell ad placements in your emails (header, footer, inline)Session
Paid subscriptionsCharge readers for access to premium newslettersSession
Tip jarAccept one-time tips from readersAPI key (monetization or send scope)

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

Sponsors

List Sponsor Slots

Returns all active and upcoming sponsor placements for your account.

GET /v1/monetization/sponsors

Headers

Authorization: Bearer msk_...

Response

[
  {
    "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"
  }
]

position values: "header" · "footer" · "inline"

Create a Sponsor Slot

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

POST /v1/monetization/sponsors

Headers

Authorization: Bearer msk_...

Request body

{
  "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"
}
FieldTypeRequiredDescription
sponsor_namestringYesDisplay name of the sponsor
logo_urlstringYesHTTPS URL to sponsor logo
target_urlstringYesClick-through URL
positionstringYesheader, footer, or inline
active_fromISO 8601YesPlacement start date
active_untilISO 8601YesPlacement end date
price_centsintegerNoAmount paid by sponsor (for records)
currencystringNoISO 4217 currency code (default: USD)

Response 201

{
  "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"
  }
}

Paid Subscriptions

List Subscriptions

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

GET /v1/monetization/subscriptions

Response

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

status values: "active" · "cancelled" · "past_due"

Create a Subscription Record

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

POST /v1/monetization/subscriptions

Request body

{
  "subscriber_email": "[email protected]",
  "plan": "monthly",
  "amount_cents": 799,
  "currency": "USD",
  "stripe_subscription_id": "sub_1OaBcDeFgHiJkL"
}
FieldTypeRequiredDescription
subscriber_emailstringYesSubscriber's email address
planstringYesYour plan identifier (e.g. monthly, annual)
amount_centsintegerYesRecurring charge amount in cents
currencystringYesISO 4217 currency code
stripe_subscription_idstringNoStripe subscription ID for reconciliation

Response 201

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

Tip Jar

Record a Tip

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

POST /v1/monetization/tip

Headers

Authorization: Bearer msk_...

Request body

{
  "email": "[email protected]",
  "name": "Alex",
  "amount_cents": 500,
  "currency": "USD",
  "message": "Love your weekly deep-dives — keep it up!",
  "stripe_payment_id": "pi_3OaBcDeFgHiJkL"
}
FieldTypeRequiredDescription
amount_centsintegerYesTip amount in cents. Min: 50 (¢50). Max: 100000 ($1,000)
currencystringNoISO 4217 code. Default: USD
emailstringNoTipper's email address
namestringNoTipper's display name
messagestringNoOptional message, max 500 characters
stripe_payment_idstringNoStripe payment intent ID for reconciliation

Response

{
  "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.

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!"
  }'
const res = await fetch('https://api.misar.io/mail/v1/monetization/tip', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer msk_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: '[email protected]',
    name: 'Alex',
    amount_cents: 500,
    currency: 'USD',
    message: 'Great newsletter!',
  }),
});

const data = await res.json();
console.log(data.net_amount_cents); // amount after platform fee
import httpx

response = httpx.post(
    "https://api.misar.io/mail/v1/monetization/tip",
    headers={"Authorization": "Bearer msk_..."},
    json={
        "email": "[email protected]",
        "name": "Alex",
        "amount_cents": 500,
        "currency": "USD",
        "message": "Great newsletter!",
    },
)
print(response.json())

Required Scopes

EndpointRequired scope
GET /v1/monetization/sponsorsSession
POST /v1/monetization/sponsorsSession + monetization
GET /v1/monetization/subscriptionsSession
POST /v1/monetization/subscriptionsSession + monetization
POST /v1/monetization/tipAPI key: monetization or send:transactional

Referrals

Previous Page

Marketplace

Next Page