Grow MisarMail through referrals — generate your share link, track referrals, climb the leaderboard, and claim milestone badges

Overview

The MisarMail referral program rewards you for inviting other creators. Share your unique link; when someone signs up through it and activates a paid plan, the referral converts. As you accumulate referrals you unlock milestone badges that you can claim.

How it works:

Generate your unique referral code and share link via the dashboard or API
Share it with friends, followers, or your audience
When someone signs up using your link, the referral is tracked as pending; once they activate a paid plan it becomes converted
As your converted-referral count grows, you reach milestone thresholds
Claim each milestone badge once you've reached its required referral count

Authentication

All referral endpoints require session authentication (cookie-based). They are dashboard-only and cannot be called with an API key.

Get Referral Stats

GET/mail/referrals

Returns your referral code, share link, aggregate counts, and the list of your referrals.

Response fields

successboolean

true when the request succeeded.

dataobject

Referral stats — see the fields below.

data.codestring | null

Your referral code (null if you haven't generated one yet).

data.shareUrlstring

Your shareable link — https://mail.misar.io/ref/{code}.

data.totalReferralsinteger

All referrals attributed to you.

data.pendingReferralsinteger

Referrals that signed up but haven't activated a paid plan.

data.convertedReferralsinteger

Referrals that activated a paid plan.

data.rewardedReferralsinteger

Referrals that have been rewarded.

data.referralsArray<object>

Individual referrals. Each has id, refereeEmail, status, source, createdAt, convertedAt, rewardedAt.

curl https://api.misar.io/mail/referrals \
  -H "Cookie: sb-access-token=YOUR_SESSION"

{
  "success": true,
  "data": {
    "code": "abc123",
    "shareUrl": "https://mail.misar.io/ref/abc123",
    "totalReferrals": 14,
    "pendingReferrals": 5,
    "convertedReferrals": 9,
    "rewardedReferrals": 4,
    "referrals": [
      {
        "id": "ref_01j8abc12",
        "refereeEmail": "friend@example.com",
        "status": "converted",
        "source": "twitter",
        "createdAt": "2025-11-01T10:00:00Z",
        "convertedAt": "2025-11-03T14:22:00Z",
        "rewardedAt": null
      }
    ]
  }
}

Generate Referral Code

POST/mail/referrals/generate

Generates your referral code and share link, or returns your existing one — the operation is idempotent, so calling it again returns the same code. Optionally records the share source.

Request body

sourcestringbodydefault: direct

Where the code is being shared from. One of direct, email, twitter, linkedin, copy_link.

Response fields

successboolean

true when the code was generated or fetched.

codestring

Your referral code.

shareUrlstring

Your shareable link — https://mail.misar.io/ref/{code}.

{ "source": "twitter" }

{
  "success": true,
  "code": "abc123",
  "shareUrl": "https://mail.misar.io/ref/abc123"
}

Leaderboard

GET/mail/referrals/leaderboard

Returns the top referrers (up to 50) plus your own rank. Other users' names are anonymized; your own entry is marked isSelf.

Response fields

successboolean

true when the request succeeded.

data.leaderboardArray<object>

Ranked entries. Each has rank, userId (your own id, or null for others), displayName, isSelf, totalReferrals, activeReferrals.

data.myRankinteger | null

Your position on the leaderboard, or null if you have no referrals yet.

curl https://api.misar.io/mail/referrals/leaderboard \
  -H "Cookie: sb-access-token=YOUR_SESSION"

{
  "success": true,
  "data": {
    "leaderboard": [
      { "rank": 1, "userId": null, "displayName": "Al***", "isSelf": false, "totalReferrals": 87, "activeReferrals": 60 },
      { "rank": 2, "userId": null, "displayName": "Sa***", "isSelf": false, "totalReferrals": 64, "activeReferrals": 51 }
    ],
    "myRank": 12
  }
}

List Milestones

GET/mail/referrals/milestones

Returns all milestone badge definitions, ordered by the referral count required to reach them.

Response fields

successboolean

true when the request succeeded.

dataArray<object>

Milestone definitions. Each has id, name, description, referrals_required, badge_icon, badge_color.

curl https://api.misar.io/mail/referrals/milestones \
  -H "Cookie: sb-access-token=YOUR_SESSION"

{
  "success": true,
  "data": [
    {
      "id": "milestone_1",
      "name": "First Referral",
      "description": "Refer your first creator",
      "referrals_required": 1,
      "badge_icon": "seedling",
      "badge_color": "#22c55e"
    },
    {
      "id": "milestone_10",
      "name": "Connector",
      "description": "Refer 10 creators",
      "referrals_required": 10,
      "badge_icon": "network",
      "badge_color": "#16a34a"
    }
  ]
}

Claim a Milestone Badge

POST/mail/referrals/claim

Claims a milestone badge once you've reached its required referral count. Claiming is idempotent per milestone.

Request body

milestone_idstringbodyrequired

The milestone to claim.

Response fields

successboolean

true when the badge was claimed.

data.milestoneNamestring

The name of the claimed milestone.

{ "milestone_id": "milestone_10" }

{
  "success": true,
  "data": { "milestoneName": "Connector" }
}

Error cases:

Status	Error	Meaning
`400`	`milestone_id is required`	Missing or invalid body
`404`	`Milestone not found`	No milestone with that ID exists
`422`	`You need N referrals to claim this milestone …`	Referral threshold not yet met
`409`	`Milestone already claimed`	You've already claimed this badge

Get Claimed Milestones

GET/mail/referrals/milestone-claims

Returns the milestone badges you've already claimed.

Response fields

successboolean

true when the request succeeded.

dataArray<object>

Claimed badges. Each has milestone_id, claimed_at, reward_applied.

curl https://api.misar.io/mail/referrals/milestone-claims \
  -H "Cookie: sb-access-token=YOUR_SESSION"

{
  "success": true,
  "data": [
    {
      "milestone_id": "milestone_1",
      "claimed_at": "2025-11-03T14:22:00Z",
      "reward_applied": true
    }
  ]
}

Nudge

GET/mail/referrals/nudge

Returns a short share prompt for the dashboard — your code, link, current referral count, and a suggested nudge message. This endpoint does not send any email.

Response fields

successboolean

true when the request succeeded.

data.codestring | null

Your referral code.

data.urlstring | null

Your share link.

data.referralCountinteger

Number of people who signed up with your link.

data.nudgeMessagestring

A ready-to-display prompt encouraging you to share.

curl https://api.misar.io/mail/referrals/nudge \
  -H "Cookie: sb-access-token=YOUR_SESSION"

{
  "success": true,
  "data": {
    "code": "abc123",
    "url": "https://mail.misar.io/ref/abc123",
    "referralCount": 3,
    "nudgeMessage": "3 friends signed up with your link — share more to unlock badges!"
  }
}

Log a Share

POST/mail/referrals/log-share

Records that you shared your referral link on a given channel. Used to display share activity in the dashboard — it does not affect referral counts.

Request body

sourcestringbodydefault: direct

One of copy_link, email, twitter, linkedin, direct.

Response fields

successboolean

true when the share was logged.

{ "source": "twitter" }

{ "success": true }