Grow MisarMail through referral rewards — generate referral links, track milestones, and claim credits

Overview

The MisarMail referral system rewards you for inviting other creators. Each successful referral earns you credits that apply toward your subscription. As you accumulate referrals, you unlock milestones that carry additional rewards — including plan upgrades.

How it works:

Generate your unique referral link via the dashboard or API
Share it with friends, followers, or your audience
When someone signs up using your link and activates a paid plan, they count as a successful referral
Credits are automatically added to your account — no manual claiming required for credits
Milestone rewards (e.g. plan upgrades) must be explicitly claimed once you qualify

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

Get Referral Stats

Returns your current referral statistics, credit balances, and progress toward the next milestone.

GET /api/referrals

Response

{
  "referralLink": "https://misarmail.com/signup?ref=abc123",
  "totalReferrals": 14,
  "successfulReferrals": 9,
  "creditsEarned": 4500,
  "creditsRedeemed": 1000,
  "currentMilestone": {
    "id": "milestone_5",
    "referralsRequired": 5,
    "reward": { "type": "credits", "amount": 2000 }
  },
  "nextMilestone": {
    "id": "milestone_10",
    "referralsRequired": 10,
    "reward": { "type": "plan_upgrade", "amount": 1 }
  }
}

Field	Description
`totalReferrals`	All sign-ups attributed to your link (including pending)
`successfulReferrals`	Referrals who activated a paid plan
`creditsEarned`	Lifetime credits earned from referrals
`creditsRedeemed`	Credits already applied to invoices
`currentMilestone`	The last milestone you've reached (null if none)
`nextMilestone`	The next milestone you're working toward

Generate Referral Link

Generates a new referral code and link, or returns your existing one. Calling this again rotates your code — existing referrals already attributed to the old code are preserved.

POST /api/referrals/generate

Response

{
  "referralCode": "abc123",
  "referralLink": "https://misarmail.com/signup?ref=abc123"
}

Rotating your referral code invalidates the old link for new sign-ups. Always update your published links after rotating.

Claim a Referral Code

Apply someone else's referral code to your account. This must be done within 30 days of account creation. Credits are awarded to both the referrer and the new user.

POST /api/referrals/claim

Request body

{ "code": "abc123" }

Response

{
  "success": true,
  "creditsAwarded": 500
}

Field	Description
`creditsAwarded`	Credits added to your account as a new-user welcome bonus

Error cases:

Error	Meaning
`code_not_found`	The referral code does not exist
`self_referral`	You cannot use your own referral code
`already_claimed`	You have already claimed a referral code
`window_expired`	More than 30 days have passed since your account was created

Leaderboard

Returns the top referrers anonymously — only rank, referral count, and credits earned are shown. No usernames or emails are exposed.

GET /api/referrals/leaderboard

Response

[
  { "rank": 1, "referrals": 87, "creditsEarned": 43500 },
  { "rank": 2, "referrals": 64, "creditsEarned": 32000 },
  { "rank": 3, "referrals": 51, "creditsEarned": 25500 }
]

List Milestones

Returns all milestone definitions in the program, including their reward types and thresholds.

GET /api/referrals/milestones

Response

[
  {
    "id": "milestone_1",
    "referralsRequired": 1,
    "reward": { "type": "credits", "amount": 500 }
  },
  {
    "id": "milestone_5",
    "referralsRequired": 5,
    "reward": { "type": "credits", "amount": 2000 }
  },
  {
    "id": "milestone_10",
    "referralsRequired": 10,
    "reward": { "type": "plan_upgrade", "amount": 1 }
  },
  {
    "id": "milestone_25",
    "referralsRequired": 25,
    "reward": { "type": "credits", "amount": 15000 }
  }
]

Reward types:

Type	Description
`credits`	`amount` credits added to your balance (1 credit = $0.01 USD)
`plan_upgrade`	Your plan is upgraded by `amount` tiers at no charge

Get Claimed Milestones

Returns all milestones you have already claimed.

GET /api/referrals/milestone-claims

Response

[
  {
    "milestoneId": "milestone_1",
    "claimedAt": "2025-11-03T14:22:00Z",
    "reward": { "type": "credits", "amount": 500 }
  }
]

Claim a Milestone

Once you reach a milestone's referral threshold, call this endpoint to claim the reward. Credits from milestones are not automatic — you must claim them explicitly.

POST /api/referrals/milestone-claims

Request body

{ "milestoneId": "milestone_5" }

Response

{
  "success": true,
  "reward": { "type": "credits", "amount": 2000 }
}

Error cases:

Error	Meaning
`milestone_not_found`	No milestone with that ID exists
`threshold_not_met`	You haven't reached the required referral count yet
`already_claimed`	You've already claimed this milestone

Nudge a Pending Referral

Send a reminder email to someone who signed up using your referral link but hasn't activated a paid plan yet. Limited to one nudge per referral per week.

POST /api/referrals/nudge

Request body

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

Response

{ "success": true }

The nudge email is sent from MisarMail on your behalf. It does not expose your email address to the recipient.

Log a Share

Track when you share your referral link on a platform. Used to display your share activity in the dashboard — does not affect referral counts.

POST /api/referrals/log-share

Request body

{ "platform": "twitter" }

Accepted platform values: "twitter", "linkedin", "email", "copy"

Response

{ "success": true }

Credits Explained

1 credit = $0.01 USD. Credits accumulate in your balance and are automatically applied to your next invoice before charging your payment method.

Credits do not expire as long as your account is active. If you downgrade or cancel, unused credits remain available if you reactivate within 12 months.