activate_list

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. 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.

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 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.
`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

Send Luma invites
Record invites you sent

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.

Ask the user which event

Never choose for them, even when exactly one is listed.

Preview

Call action: "preview" with list_id and that target_event_id. Nothing is sent.

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.

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.

Check progress

Call action: "status" with the activation_id.

Confirm the user sent them

Use this door only when the user says they invited these people themselves. Never choose it for them.

Preview

Call action: "preview", destination_type: "external", list_id and target_channel_id. Show the counts.

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[]`
preview (Luma)	target_event_id, event_name, event_starts_at, event_ends_at, eligible_count, excluded_count, total_count, excluded_by_reason, provenance_composition , 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.

{
  "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.

save_list: make the List first.
get_lists: find the list_id.
get_event_details: read the logged invites back.
Playbook: Fill the room in the two weeks before.

Get started

How heyBTW MCP works

Playbooks

Tools: orientation

Tools: events and rosters

Tools: people and invites

Tools: after the event

Tools: accounts and partners

Tools: pipeline

When to use it

Parameters

Workflow

Invite log

Response

Rules the agent must follow

Errors and gaps

​When to use it

​Parameters

​Workflow

​Invite log

​Response

​Rules the agent must follow

​Errors and gaps

​Related

When to use it

Parameters

Workflow

Invite log

Response

Rules the agent must follow

Errors and gaps

Related