Browse docsissue_invitations
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. 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.
There is no caller-supplied replay key. After an uncertain response, read 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#
{
"groupPublicId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"people": [{ "name": "Synthetic Pat", "email": "pat@example.test" }],
"note": "Join us."
}
Result (synthetic data):
{
"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_invitationsshows the links already open, to resend one or avoid inviting twice.- Privacy and safety on who sends an invitation.