API reference

Sign-up

For the browser, with the public key: put an address on the list and read the leaderboard.

POST/api/v1/subscribePublic key, from the browser

Stores the address as pending and sends the confirmation mail. Meant to be called from a page in the browser: the Origin header must be one of the product's allowed origins. The answer is the same whether the address is new, pending or already confirmed, so nobody can find out who is on a list.

A pending address gets at most one mail every 10 minutes. A filled website field (the honeypot) is answered with success, and nothing is stored. A browser that submits a plain HTML form (Accept: text/html) is redirected to the hosted pages instead of getting JSON.

curl -X POST $NEARLYIN_URL/api/v1/subscribe \
  -H 'Origin: https://tasselo.app' -H 'Content-Type: application/json' \
  -d '{"productKey":"ni_pk_live_…","email":"ada@example.com","elapsedMs":4200}'

Parameters

Originheader · string · required: Set by the browser. Must be an allowed origin of the product, or this service itself.

Body

productKeystring · required: Public key of the product (ni_pk_live_… or ni_pk_test_…).
emailstring · required
elapsedMsinteger · required: Milliseconds between showing the form and submitting it. Sign-ups faster than 1.5 seconds are refused as too_fast.
websitestring · optional: Honeypot: a field no human sees. Must be empty or missing.
refstring · optional: Referral code from the page address (?ref=). The form of the package sends it on its own. A sign-up through it that confirms moves the referrer up the line. Unknown codes are ignored.
sourcestring · optional: Where the visitor came from, for the counts per source in the dashboard: a short name such as newsletter or reddit.com. The form of the package sends utm_source of the page, else the site before it. Counted per day only, never stored with the entry. Names that are not plain (letters, digits, ., _, -, at most 60) count as direct.

Responses

200 Accepted. Says nothing about whether a mail went out.

{
  "accepted": true
}

400 invalid_request: The request could not be read or is missing a required field. / invalid_email: This is not a valid email address.

403 origin_not_allowed: This origin may not sign up for this product.waitlist_closed: The product closed its waitlist; nobody new is taken.

404 unknown_product: No product has this public key.

422 email_not_allowed: The product only takes addresses of certain domains, or no free mail addresses, and this address is not one it takes.too_fast: The form was submitted too fast, or without its elapsed time.

429 rate_limited: Too many requests. Retry after the number of seconds in Retry-After.

Read the referral leaderboard

GET/api/v1/leaderboardPublic key, from the browser

The ten entries with the most confirmed referrals, for products that show a leaderboard (a setting in the dashboard); otherwise the list is empty. Addresses are shortened to the first letters and the top-level domain. Public like the product key; pages of the product's allowed origins may read it from the browser.

curl "$NEARLYIN_URL/api/v1/leaderboard?productKey=$NEARLYIN_PUBLIC_KEY"

Parameters

productKeyquery · string · required: The public key of the product (ni_pk_…).

Responses

200 The leaderboard, most referrals first.

{
  "leaderboard": [
    {
      "email": "a***@e***.com",
      "referrals": 12
    },
    {
      "email": "b***@m***.de",
      "referrals": 7
    }
  ]
}

400 invalid_request: The request could not be read or is missing a required field.

404 unknown_product: No product has this public key.