Skip to main content
Writes to your heyBTW workspace. On confirm (or a call with no action) it creates person records. It never saves a List, never sends an invite and never enriches anyone. Preview first.
Your audience often lives in a CRM, not in past event sign-ups. import_people brings those people into heyBTW by email so save_list can keep them as a List and activate_list can invite them. Follows the heyBTW MCP rules.

When to use it

  • “Take the 40 VPs I just pulled from HubSpot and get them ready to invite to the LA dinner.”
  • “Import this Sales Navigator export with each person’s city.”
  • “Load my CRM list in chunks, then save it as a List.”
  • “Mark which of these my teammate Tony already knows.”
Imported people are not sign-ups or attendees. They appear in no roster, funnel or attribution count. For a file of event attendees, use record_signups or create_import_link instead.

Parameters

location is where the person is, as the source states it. Never pass a company address and never coordinates. The city is stored as stated and never geocoded.

Workflow

1

Preview the first chunk

Call action: "preview" with up to about 50 people and a fresh client_request_id. Nothing is imported. Read row_outcomes, workspace_overlap and company_carry.
2

Tell the user what the preview found

Relay workspace_overlap.sentence and company_carry.sentence as written. Offer each candidates_by_name entry for the user to confirm. Never call two emails the same person on your own. Name any suspect_rows.
3

Append the rest

For more people, call action: "append" with the import_token, the next chunk and a fresh client_request_id. Report the staged totals, never one chunk’s. At most 2,000 people staged in all.
4

Confirm once

After the user agrees, call action: "confirm" with the import_token, a fresh client_request_id and no people. It imports every staged person once.
5

Save the List

Pass data[0].member_emails to save_list unchanged.
On a transport error, retry with the same client_request_id. A committed import is replayed (idempotent_replay: true), never repeated.

Response

Per person, by email (case-insensitive): someone the workspace already holds is merged (nothing overwritten), an erased person is rejected and stays erased, a malformed address is rejected, anyone else is created. This sample is trimmed from a real preview of fictional example.org people sent today. Nothing was imported.

Rules the agent must follow

  • Preview first, show the user, and confirm only after they agree.
  • Relay workspace_overlap.sentence and company_carry.sentence as written.
  • Never merge two emails as one person without the user’s confirmation.
  • Leave a suspect row out of save_list only if the user agrees. Never exclude anyone on your own.
  • Never treat an import as evidence that anyone registered or attended.
  • Never pass a company’s address as a person’s location.

Errors and gaps

  • Rejected rows are disclosed in gaps. Correct a malformed address and send it in a later append. Do not re-import an erased person.
  • invalid_parameter: a person carries a key this tool does not accept, people is empty or over 500, source_system is missing beside an external_id, or a chunk was sent again under a new client_request_id.
  • insufficient_scope: the OAuth token lacks mcp:tools:write. Nothing is imported.
  • Writing needs no plan: every workspace can write.
  • internal_error: retry once with the same client_request_id.