# Invite someone

`POST https://api.mailmasker.org/api/v1/invites`

Email someone a link they can use to make an account.

- Who can use it: Any signed-in account
- Area: Invites
- Answers 201 Created when it works
- Page: https://developer.mailmasker.org/invite-send

Makes a one-time sign-up link and emails it to them, with your note if you add one. The answer holds the link itself as `url`, so you can also pass it on another way. It stops working at `expires_at`.

## Parameters

| Name | In | Required | What it is | Example |
|---|---|---|---|---|
| `recipient_email` | body | yes | Their email address, where the link is sent. | `friend@example.com` |
| `message` | body | no | A note from you, put in the email and shown on the sign-up page. | `Come and join me here.` |
| `channel` | body | no | cli (the default) or web, and the email is sent for you. roundcube_plugin sends no email, leaving the link for you to deliver. |  |

## Good to know

- Past your limit of waiting invites, or of invites sent in the last day, the answer is 429 (see See your invite limits).
- A second invite to someone who already has a pending one from you answers 409. An address that doesn't look like one answers 400.
- If the email can't be sent, the invite is still made. The answer adds a `warning`, and the link in `url` still works.
- Someone whose address is on one of this system's own mail domains can't use an invite; the sign-up page turns them away.

## Examples

cURL:

```bash
curl -s -X POST 'https://api.mailmasker.org/api/v1/invites' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"recipient_email":"friend@example.com","message":"Come and join me here."}'
```

Perl:

```perl
use Mojo::Base -strict;
use Mojo::UserAgent;

my $ua  = Mojo::UserAgent->new;
my $res = $ua->post('https://api.mailmasker.org/api/v1/invites',
    { Authorization => "Bearer $ENV{TOKEN}" },
    json => { recipient_email => 'friend@example.com', message => 'Come and join me here.' })->result;
die $res->code, ' ', ($res->json('/error') // $res->message), "\n" unless $res->is_success;
print $res->body, "\n";
```

homelab-cli:

```bash
homelab-cli invite send --to friend@example.com --message "Come and join me here."
```

## Response

201 Created:

```json
{
  "id": 12,
  "token": "f00dfeedf00dfeedf00dfeedf00dfeedf00dfeedf00dfeedf00dfeedf00dfeed",
  "sender_email": "you@example.com",
  "recipient_email": "friend@example.com",
  "channel": "cli",
  "message": "Come and join me here.",
  "status": "pending",
  "created_at": "2026-11-03 21:42:10.123456-06",
  "expires_at": "2026-11-17 21:42:10.123456-06",
  "accepted_at": null,
  "accepted_user_email": null,
  "revoked_at": null,
  "revoked_by_email": null,
  "url": "https://invite.example.com/invite/f00dfeedf00dfeedf00dfeedf00dfeedf00dfeedf00dfeedf00dfeedf00dfeed"
}
```