---
title: "Invite a friend to inboxy."
method: POST
path: "/v1/mail/invite"
tags: ["Mail"]
---

# Invite a friend to inboxy.

`POST /v1/mail/invite`

## Request

- Base URL: `https://api.inboxy.net`
- URL: `https://api.inboxy.net/v1/mail/invite`
- Auth: HTTP bearer

REST mirror of the MCP `mail_invite` tool. Requires `send` scope. One magic-link email is sent from `invites@mail.inboxy.net`. Capped at 10 per rolling 30 days per inviter. Refuses self-invites, existing-user invites, and reserved local-parts.

## Request body

- MailInviteRequest: Invite a friend to inboxy. The recipient receives a single magic-link email from `invites@mail.inboxy.net` — no further mail until they accept. Capped at 10 invites per rolling 30 days per inviter. Self-invites, invites to existing users, and invites to reserved local-parts are refused.
  - `to` string, email, required: Invitee's personal email.
  - `personal_note` string: Optional ≤500-char note included in the invite body, labelled as written by the inviter. Links, web addresses and email addresses are refused (`note_has_link`).

## Response `200`

Invite queued; magic-link valid 30 days.

- MailInviteResult
  - `invite_id` string, required: Opaque id; surfaces in `audit_log`.
  - `expires_at` integer, required: Unix seconds when the invite token expires (30 days from issue).
  - `invites_remaining` integer, required: Remaining invites in the caller's rolling 30-day window.

## Other responses

- `400`: Validation failure (`to_missing`, `to_unparseable`, `recipient_reserved`, `self_invite`, `note_too_long`, `note_has_link`).
- `403`: `recipient_already_user` — the invitee already has an inboxy account.
- `429`: `invite_cap_reached` — body includes `remaining: 0` + `resets_at` (Unix seconds).

---

[API](https://skmtc.dev/inboxy/apis/inboxy-api.md) · [All operations](https://skmtc.dev/inboxy/apis/inboxy-api/llms.txt) · [OpenAPI document](https://skmtc.dev/inboxy/apis/inboxy-api/revisions/25155a8dec0f?raw)