Docs · vipvap

1. Sign up and grab your API key

Open the sign-up page, create an account, and the dashboard shows your first API key — a one-time reveal.

2. Send your first OTP

Hit POST /v1/send with a Bearer key and a JSON body.

curl -X POST https://api.vipvap.xyz/v1/send \
  -H "Authorization: Bearer vp_live_a4f2…" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "alice@acme.com",
    "code":      "418917"
  }'

const res = await fetch("https://api.vipvap.xyz/v1/send", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.VIPVAP_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    recipient: "alice@acme.com",
    code:      "418917",
  }),
});
const data = await res.json();
console.log(data.id, data.status);

import os, requests

resp = requests.post(
    "https://api.vipvap.xyz/v1/send",
    headers={"Authorization": f"Bearer {os.environ['VIPVAP_KEY']}"},
    json={
        "recipient": "alice@acme.com",
        "code":      "418917",
    },
    timeout=5,
)
resp.raise_for_status()
data = resp.json()

<?
$ch = curl_init("https://api.vipvap.xyz/v1/send");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Bearer " . getenv("VIPVAP_KEY"),
  "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  "recipient" => "alice@acme.com",
  "code"      => "418917",
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true);
?>

Response

// 200 OK
{
  "id":      "snd_3f2a9b",
  "status":  "delivered",
  "to":      "alice@acme.com",
  "from":    "vipvap <notify@vipvap.xyz>",
  "subject": "vipvap: your verification code",
  "expires_in_minutes": 10,
  "quota_remaining":    1949
}

API reference

POST

/v1/send

Send one OTP email. Authenticated by Bearer key.

GET

/v1/usage

Current period usage and quota remaining.

POST /v1/send

Request body

Field	Type	Required	Description
recipient	string	required	Recipient email address.
code	string	required	The OTP. 4–12 chars; whatever your flow expects.
country	string	optional	ISO 3166-1 alpha-2 country for the recipient (e.g. `"US"`). Powers the Countries analytics and the country filter in Send logs. Omit it and vipvap falls back to the request's geolocation header, then to `unknown`.

Response — 200

Field	Type	Description
id	string	Send ID, used by the dashboard logs.
status	string	`delivered`, `queued`, `bounced`, `failed`.
to	string	Recipient address.
from	string	Rendered From line. Always `vipvap <notify@vipvap.xyz>`.
subject	string	Rendered subject line. Always `vipvap: your verification code`.
expires_in_minutes	integer	Default expiry applied to the message body.
quota_remaining	integer	Hard cap minus used, after this send.

Errors

Status	code	What it means
401	invalid_api_key	Missing or wrong Bearer token.
400	invalid_recipient	Address is malformed.
400	invalid_code	Code is missing or wrong shape.
429	quota_exceeded	Hard cap reached. No overages — upgrade in the dashboard to lift it.

Country detection

Every send is tagged with the recipient's country so you can see where your OTPs go. vipvap resolves it in this order and never guesses:

The country you pass in the request (or an X-Country header), if it is a valid ISO alpha-2 code.
A geolocation header set by the proxy/CDN in front of your vipvap instance — CF-IPCountry, X-Vercel-IP-Country, X-AppEngine-Country, X-Country-Code or X-Geo-Country.
Otherwise unknown. A send with no location signal is labelled unknown, never a wrong country.

The dashboard's Countries view maps each country that received OTPs, darker and larger where more codes went, with per-country volume and delivery rate over Today / 7 days / 30 days / all time. Send logs show the country per row and can be filtered to one country.

Webhooks

Set a webhook URL in the dashboard's Settings page and we'll POST delivery status callbacks as a single vipvap-delivery event.

{
  "event": "vipvap.delivery",
  "data": {
    "id":         "snd_3f2a9b",
    "status":     "delivered",
    "recipient":  "alice@acme.com"
  }
}

Contact

Need a higher quota, a separate sending segment, or a custom agreement? Email hi@vipvap.xyz.

Legal

vipvap Inc. Terms of Service and Privacy Policy apply. vipvap transmits only OTP emails. Sending other content types (marketing, transactional, anything non-OTP) is a violation of the terms and grounds for account suspension.

The quickstart.