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

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/api/referrals

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

Response fields

referralLinkstring

Your shareable referral link.

totalReferralsinteger

All sign-ups attributed to your link (including pending).

successfulReferralsinteger

Referrals who activated a paid plan.

creditsEarnedinteger

Lifetime credits earned from referrals.

creditsRedeemedinteger

Credits already applied to invoices.

currentMilestoneobject

The last milestone you've reached (null if none).

nextMilestoneobject

The next milestone you're working toward.

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

Generate Referral Link

POST/mail/api/referrals/generate

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.

Response fields

referralCodestring

Your referral code.

referralLinkstring

Your shareable referral link.

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

POST/mail/api/referrals/claim

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.

Request body

codestringbodyrequired

The referral code to apply.

Response fields

successboolean

true when the code was applied.

creditsAwardedinteger

Credits added to your account as a new-user welcome bonus.

{ "code": "abc123" }

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

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

GET/mail/api/referrals/leaderboard

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

Response fields

rankinteger

The referrer's position on the leaderboard.

referralsinteger

Number of referrals attributed to the entry.

creditsEarnedinteger

Lifetime credits earned by the entry.

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

List Milestones

GET/mail/api/referrals/milestones

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

Response fields

idstring

The milestone identifier.

referralsRequiredinteger

Referrals needed to reach the milestone.

rewardobject

The milestone reward — a type (credits or plan_upgrade) and amount.

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

GET/mail/api/referrals/milestone-claims

Returns all milestones you have already claimed.

Response fields

milestoneIdstring

The claimed milestone's identifier.

claimedAtstring

ISO-8601 time the milestone was claimed.

rewardobject

The reward granted — a type and amount.

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

Claim a Milestone

POST/mail/api/referrals/milestone-claims

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.

Request body

milestoneIdstringbodyrequired

The milestone to claim.

Response fields

successboolean

true when the milestone was claimed.

rewardobject

The reward granted — a type and amount.

{ "milestoneId": "milestone_5" }

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

POST/mail/api/referrals/nudge

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.

Request body

emailstringbodyrequired

The pending referral's email address.

Response fields

successboolean

true when the nudge was sent.

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

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

POST/mail/api/referrals/log-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.

Request body

platformstringbodyrequired

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

Response fields

successboolean

true when the share was logged.

{ "platform": "twitter" }

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