> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mithunai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Invite a person by email

> Email someone a link to join your organisation, with a role. They need no account beforehand. Takes a signed-in console session, never an API key.

Emails an invitation to join your organisation. The person does not need an account: they open the link, choose a password, and their account and membership are created together. If the address already has an account, they confirm with that account's password and are added to your organisation.

The link works **once** and for **seven days**. It is sent only to the address you give and is never returned by this API.

The response is the same whether or not the address already has an account, so this endpoint cannot be used to find out who is registered.

This endpoint takes a **signed-in console session**, not an API key. Send the session cookies your browser received when you signed in, plus the `X-CSRF-Token` header set to the value of the `csrf_token` cookie. A request authenticated with an `mithunai_sk_` key is refused with `403`.

You need the owner or admin role, and you cannot invite to a role above your own; asking for one returns `403`. Ownership is never given by invitation, so `owner` returns `400`.

* `409` — the address is already a member of your organisation, or already has an invitation that has not been accepted. [Send that one again](https://docs.mithunai.com/api-reference/invitations/resend-invitation.md) instead.
* `429` — your organisation has sent 30 invitations in the last hour. Wait and try again.
* `503` — this deployment is not set up to send email. Nothing was created; ask whoever runs the deployment.
* `502` — the email provider refused the message. Nothing was created; try again shortly.

See [Invitations](https://docs.mithunai.com/administration/invitations.md).

**X-CSRF-Token** `string` *required*

The value of your session's `csrf_token` cookie (named `__Host-csrf_token` when the console is
served over HTTPS without a shared cookie domain). A missing or mismatched token returns `401`.

**email** `string` *required*

The address to invite. Up to 255 characters. It is stored and matched in lower case.

**role** `string` (default: normal)

The role they get when they accept: `admin`, `editor`, `normal` or `dataset_operator`. `normal` is
the member role. See [Organisations and roles](https://docs.mithunai.com/concepts/organizations-and-roles.md).

## Response

Returns `201 Created` with the invitation. The email has been handed to the email provider by the time you receive it.

**id** `string` *required*

The invitation's ID (UUID). Use it to send the invitation again or withdraw it.

**email** `string` *required*

The invited address, in lower case.

**role** `string` *required*

The role the person will get.

**status** `string` *required*

`pending` while the link works; `expired` once its seven days have passed.

**invited\_by\_name** `string | null` *required*

The display name of the member who sent it.

**created\_at** `string` *required*

When it was first sent, ISO 8601 in UTC.

**expires\_at** `string` *required*

When the current link stops working, ISO 8601 in UTC.

**last\_sent\_at** `string` *required*

When it was last sent, ISO 8601 in UTC.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
# cookies.txt holds the cookies from your signed-in console session.
curl --request POST "$MITHUNAI_URL/mithunai/api/v1/invitations" \
  --cookie cookies.txt \
  --header "X-CSRF-Token: $MITHUNAI_CSRF_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"email": "sarah.chen@example.com", "role": "editor"}'
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import os
from http.cookiejar import MozillaCookieJar

import requests

jar = MozillaCookieJar("cookies.txt")
jar.load()

response = requests.post(
    f"{os.environ['MITHUNAI_URL']}/mithunai/api/v1/invitations",
    cookies=jar,
    headers={"X-CSRF-Token": os.environ["MITHUNAI_CSRF_TOKEN"]},
    json={"email": "sarah.chen@example.com", "role": "editor"},
    timeout=30,
)
response.raise_for_status()
print(response.json()["id"])
```

```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
// Runs in a page on the MITHUNAI console's own origin, while signed in.
// csrfToken is the value of the csrf_token cookie.
const response = await fetch('/mithunai/api/v1/invitations', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json', 'X-CSRF-Token': csrfToken },
  body: JSON.stringify({ email: 'sarah.chen@example.com', role: 'editor' }),
})
console.log((await response.json()).id)
```

```json 201 theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "9d4e2a71-3c5b-4f80-a6d1-8e7b2c0f4a13",
  "email": "sarah.chen@example.com",
  "role": "editor",
  "status": "pending",
  "invited_by_name": "Alex Mercer",
  "created_at": "2026-10-13T09:12:05.640021+00:00",
  "expires_at": "2026-10-20T09:12:05.640021+00:00",
  "last_sent_at": "2026-10-13T09:12:05.640021+00:00"
}
```

```json 409 theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "code": "conflict", "message": "That address already has an invitation. Re-send it instead." }
```

```json 503 theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "code": "dependency_failure", "message": "This deployment cannot send e-mail yet." }
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.