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

# activate_list

> Send a saved List as Luma invites to an event, or record invites you sent yourself, and read the resulting funnel.

> [!WARNING]
>
> This tool SENDS REAL INVITES. With `destination_type: "luma_event"` (the default), `action: "confirm"` sends Luma invites to real people, and a send cannot be recalled. It only sends after a preview and the user's explicit confirmation. With `destination_type: "external"` it sends nothing: it records invites the user already sent themselves.

activate\_list is the step after [save\_list](https://heybtw.com/docs/tools/save-list.md). It takes a `list_id` and either sends the List to a Luma event the user names, or records that the user invited these people on their own so the List's funnel counts them. It also reports a send's progress and the invited-to-approved funnel.

Follows the [heyBTW MCP rules](https://heybtw.com/docs/mcp/rules.md).

## When to use it

* "Send the LA dinner List as Luma invites."
* "I emailed these 20 people myself yesterday. Record them as invited to the SF Open House."
* "Did my send go out?"
* "How many people from that List approved?"

## Parameters

| Parameter | Type | Required | Notes |
| - | - | - | - |
| `action` | string | No | `events`, `preview` (default), `confirm`, `status`, `funnel`. |
| `list_id` | string | On preview, confirm, funnel | From [get\_lists](https://heybtw.com/docs/tools/get-lists.md) or save\_list. |
| `destination_type` | string | No | `luma_event` (default, sends) or `external` (records, sends nothing). Preview and confirm only; refused on events, status and funnel. |
| `target_event_id` | string | Luma preview and confirm | From `action: "events"`. Never inferred. |
| `target_channel_id` | string | External preview and confirm | The collab's `channel_id` from [list\_events](https://heybtw.com/docs/tools/list-events.md). |
| `client_request_id` | string | On confirm | A fresh hyphenated UUID. |
| `typed_count` | integer | Luma sends over 2,500 | The eligible count, typed back by the user. |
| `weekly_warning_acknowledged` | boolean | When the preview exceeded the weekly reference | Luma only. |
| `message` | string | No | Luma only. |
| `invited_at` | string | No | External only. ISO-8601 with an offset, not in the future. Defaults to now. |
| `invited_channel` | string | No | External only. `personal_email`, `sequence`, `linkedin`, `partner` or `other`. `luma` is refused. Leave it out when the user does not say; `other` is recorded. |
| `invite_log` | string | No | Preview and confirm. `person` or `count`. Default: `person` up to 2,500 recipients, `count` above. |
| `activation_id` | string | On status | From a confirm or the funnel. Also narrows funnel to one send. |
| `contract_version` | string | No | Omit for v1. |

## Workflow

> [tab] Send Luma invites
>
> **1. List the destinations**
>
> Call `action: "events"`. It lists only Luma events this workspace can send to. A collab with no linked Luma event does not appear, and an empty list with `credential_available: true` means no sendable Luma event exists yet.
>
> **2. Ask the user which event**
>
> Never choose for them, even when exactly one is listed.
>
> **3. Preview**
>
> Call `action: "preview"` with `list_id` and that `target_event_id`. Nothing is sent.
>
> **4. Show the confirmation payload**
>
> Present the eligible count, excluded reasons, the event name and date, the trailing 7-day invite usage, and the invite log note. When any members are imported, relay the provenance coverage note word for word.
>
> **5. Confirm only on an explicit go-ahead**
>
> Call `action: "confirm"` with the same `target_event_id` and a fresh `client_request_id`. Over 2,500 eligible, pass `typed_count`. If the preview exceeded the weekly reference, pass `weekly_warning_acknowledged: true`.
>
> **6. Check progress**
>
> Call `action: "status"` with the `activation_id`.

> [tab] Record invites you sent
>
> **1. Confirm the user sent them**
>
> Use this door only when the user says they invited these people themselves. Never choose it for them.
>
> **2. Preview**
>
> Call `action: "preview"`, `destination_type: "external"`, `list_id` and `target_channel_id`. Show the counts.
>
> **3. Confirm**
>
> After the user confirms, call `action: "confirm"` with the same `destination_type` and `target_channel_id` and a fresh `client_request_id`. Optional `invited_at` and `invited_channel`. Nothing is sent.

Both doors apply the same eligibility rule. A member with no event history, CRM relationship or import in this workspace is excluded, not invited. Members already recorded or sent for the same List and destination are excluded as previously sent. Never tell the user every member was invited.

If a confirm fails with `send_outcome_unknown`, retry with the same `client_request_id`. The server dedupes on it and a retry can never double-send. Any other repeat is not free: a grown dynamic List re-sends the delta.

## Invite log

`invite_log` decides whether the confirm writes one invite record per person (`person`, with who sent it) or only this activation's counts (`count`). Omitted, it is `person` up to 2,500 recipients and `count` above. The preview serves `invite_log` and `invite_log_basis` (`default_threshold` or `user_set`) and a note: relay it before the user confirms. Never record an activate\_list send again with record\_observation.

## Response

Each action returns `data[0].action` and `data[0].result`. A Luma preview and confirm were not captured for this page, because the workspace has no sendable Luma event and a confirm would send. Those shapes are from the tool's code and contract.

| Action | Fields in `result` |
| - | - |
| events | `credential_available`, `events[]` {target_event_id, event_name, event_starts_at, event_ends_at, collab_name, unselectable_reason} |
| preview (Luma) | target\_event\_id, event\_name, event\_starts\_at, event\_ends\_at, eligible\_count, excluded\_count, total\_count, excluded\_by\_reason, provenance\_composition {registrant, imported, neither}, previously\_sent\_count, week\_sent\_count, weekly\_reference, exceeds\_weekly\_reference, requires\_typed\_count, consent\_filtered, invite\_log, invite\_log\_basis |
| preview (external) | destination\_type, collab\_name, and the same counts without the weekly fields |
| confirm | activation\_id, state, counts, idempotent, invite\_log; external adds invited\_at, invited\_channel, invite\_log\_count |
| status | activation\_id, destination\_type, state, event\_name, counts, invite\_log\_count, invite\_log, failure\_code (when FAILED) |
| funnel | `activations[]`, one per send: activation\_id, target\_event\_id, event\_name, activated\_at, destination\_type, membership\_mode, members, invited, approved, no\_response, engaged\_non\_registrants, withheld, withheld\_reason |

This funnel sample is trimmed from a real call today on a test List recorded as external.

```json theme={null}
{
  "tool": "activate_list",
  "data": [
    {
      "action": "funnel",
      "result": {
        "status": "ok",
        "activations": [
          {
            "activation_id": "cmvzor6jp001708kzxf62ewjv",
            "target_event_id": null,
            "event_name": "[TEST] Guides E2E: SF Revenue Leaders Dinner",
            "activated_at": "2026-11-02T20:02:37.669Z",
            "collab_name": "[TEST] Guides E2E: SF Revenue Leaders Dinner",
            "destination_type": "external",
            "membership_mode": "snapshot",
            "members": 6,
            "invited": 6,
            "approved": 2,
            "no_response": 3,
            "engaged_non_registrants": 0,
            "withheld": false,
            "withheld_reason": null
          }
        ],
        "truncated": false
      }
    }
  ],
  "status": "ok"
}
```

## Rules the agent must follow

* Never confirm a Luma send without the user's explicit go-ahead on the preview they saw.
* Never pick the target event or the external door for the user.
* Relay the imported-members coverage note and the invite log note word for word before confirm.
* Report funnel entries one per send, each naming its event. Never sum them unless the user asks for a lifetime total.
* `withheld: true` means the host's records are restricted: say "restricted", never "no one responded". Its nulls are unknown, not zero.

## Errors and gaps

* `invalid_parameter`: a missing required parameter (for example `activation_id` on status), or an argument the action does not use, which is refused, never ignored.
* `destination_not_supported`: any `destination_type` other than `luma_event` or `external`.
* `insufficient_scope`: preview and confirm need `mcp:tools:write` on an OAuth token. events, status and funnel need no scope.
* `entitlement_required`: the plan lacks outbound agent connections.
* `send_outcome_unknown`: retry with the same `client_request_id`.
* `internal_error`: retry once.

## Related

* [save\_list](https://heybtw.com/docs/tools/save-list.md): make the List first.
* [get\_lists](https://heybtw.com/docs/tools/get-lists.md): find the `list_id`.
* [get\_event\_details](https://heybtw.com/docs/tools/get-event-details.md): read the logged invites back.
* Playbook: [Fill the room in the two weeks before](https://heybtw.com/docs/playbooks/invite-sprint.md).


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