Skip to content
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#

InputRequiredTypeDescription
groupPublicIdyesstringA group you moderate.
peopleyeslistOne 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.
notenostringYour 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:

FieldTypeDescription
name, emailstringThe person as you named them
invitationUrlstringTheir link; whoever opens it can join
subjectstringA subject line for the message
bodystringThe 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#

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

Result (synthetic data):

json
{
  "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"
}