# `issue_invitations`

Creates one invitation link per person into a group you moderate, with the words to send each one.

Annotations: `readOnlyHint: false` · `destructiveHint: false` · `idempotentHint: false` · `openWorldHint: false`

## When to use it

After the member has chosen whom to invite, often from [`suggest_group_members`](/docs/mcp/tools/suggest_group_members). Up to ten people per call, each with a name and an email address. The `note` is the invitation in the member's own words: short, warm, honest that the group is small, with no claims about what Gravity will find.

Nothing is sent. Each result carries the person's link and a ready `subject` and `body`; the member sends each invitation from their own mail. Give them the body per person, or the link alone when they prefer. Gravity never emails anyone who is not a member. Each link admits up to ten people and lasts fourteen days.

## Inputs

| Input | Required | Type | Description |
| --- | --- | --- | --- |
| `groupPublicId` | yes | string | A group you moderate. |
| `people` | yes | list | One to ten `{ name, email }` entries. Names are trimmed (1–200 characters); addresses are trimmed and lowercased (up to 320 characters). Duplicate normalized addresses reject the request. |
| `note` | no | string | Your words to each person, up to 500 characters. |

## Returns

Success returns `status`, `outcome` (`issued` or `no_change`), `sentByGravity: false`, `message`, `group` (`{ publicId, name }`), `invitations`, `skipped`, and the group's `link`. Each skip contains `name`, `email`, and `reason` (`already_member` or `already_invited`). Open-link checks cover only links you created; another moderator's addressees are private. Tell the member about the skips. Each invitation has:

| Field | Type | Description |
| --- | --- | --- |
| `name`, `email` | string | The person as you named them |
| `invitationUrl` | string | Their link; whoever opens it can join |
| `subject` | string | A subject line for the message |
| `body` | string | The message, with your note, the invitation, and the link |

Authority and recipient eligibility are rechecked during issuance. All eligible links commit together. If everyone is already a member or already has one of your open links, the call succeeds with `outcome: "no_change"`, no invitations, and explicit skips. A member who does not moderate the group gets `request_rejected`. Exceeding the shared limit of twenty links in a rolling twenty-four hours (including personal offers) returns `request_rejected` with `retry_later`, and nothing was created. Skips use no quota. Errors use the [common contract](/docs/mcp/errors-and-limits).

There is no caller-supplied replay key. After an uncertain response, read [`list_invitations`](/docs/mcp/tools/list_invitations) before retrying, following its pages before claiming complete coverage. That List covers your currently open links; absence does not prove issuance never committed. A later call can create new links after old ones expire, are revoked, or fill up; this is not original-result replay.

## Example

```json issue_invitations
{
  "groupPublicId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "people": [{ "name": "Synthetic Pat", "email": "pat@example.test" }],
  "note": "Join us."
}
```

Result (synthetic data):

```json result:issue_invitations
{
  "status": "success",
  "outcome": "issued",
  "sentByGravity": false,
  "skipped": [],
  "message": "The invitation is ready to send from your own mail. Nothing has been sent.",
  "group": { "publicId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "name": "Synthetic founders" },
  "invitations": [
    {
      "name": "Synthetic Pat",
      "email": "pat@example.test",
      "invitationUrl": "https://invites.example.test/join/cccccccccccccccccccccccccccccccc",
      "subject": "An invitation to Synthetic founders on Gravity",
      "body": "Hey Synthetic!\n\nJoin us.\n\nGravity reads between the lines of our comms to find win-wins among people we know, and it can surface useful opportunities for you too.\n\nhttps://invites.example.test/join/cccccccccccccccccccccccccccccccc"
    }
  ],
  "link": "https://www.meetgravity.ai/dashboard/groups/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
```

## Related

- [`list_invitations`](/docs/mcp/tools/list_invitations) shows the links already open, to resend one or avoid inviting twice.
- [Privacy and safety](/docs/mcp/privacy-and-safety) on who sends an invitation.
