# Create an account

`POST https://api.mailmasker.org/api/v1/auth/register`

Make a new account with an invite, an address and a password.

- Who can use it: Anyone, with no sign-in
- Area: Sign-in and tokens
- Answers 201 Created when it works
- Page: https://developer.mailmasker.org/create-account

Accounts are by invitation only: `invite_token` must be an unused invite, and creating the account uses it up. The account can sign in straight away, but this call doesn't sign it in: sign in next to get a token.

## Parameters

| Name | In | Required | What it is | Example |
|---|---|---|---|---|
| `email` | body | yes | The new account's address, which is also what it signs in with. | `newuser@example.com` |
| `password` | body | yes | The new account's password. | `$PASSWORD` |
| `invite_token` | body | yes | The token from an invite link. | `$INVITE_TOKEN` |
| `recovery_email` | body | no | An address outside this mail system, where a password-reset link can be sent. | `personal@example.com` |

## Good to know

- An address that already has an account answers 409, and the invite is not used up.
- Leaving out invite_token answers 400. An invite that is unknown, used or expired answers 403, and so does an address outside the invite's own domain (mailmasker.org).
- After ten failed sign-ins or invite attempts from one network address within 15 minutes, it answers 429; wait 15 minutes.

## Examples

cURL:

```bash
curl -s -X POST 'https://api.mailmasker.org/api/v1/auth/register' \
  -H 'Content-Type: application/json' \
  -d "{\"email\":\"newuser@example.com\",\"password\":\"$PASSWORD\",\"invite_token\":\"$INVITE_TOKEN\",\"recovery_email\":\"personal@example.com\"}"
```

Perl:

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

my $ua  = Mojo::UserAgent->new;
my $res = $ua->post('https://api.mailmasker.org/api/v1/auth/register',
    json => { email => 'newuser@example.com', password => $ENV{PASSWORD}, invite_token => $ENV{INVITE_TOKEN}, recovery_email => 'personal@example.com' })->result;
die $res->code, ' ', ($res->json('/error') // $res->message), "\n" unless $res->is_success;
print $res->body, "\n";
```

homelab-cli:

```bash
homelab-cli register newuser@example.com --invite-token "$INVITE_TOKEN"
```

## Response

201 Created:

```json
{ "id": 42, "email": "newuser@example.com" }
```