Lightmeter MCP

How to Connect to MCP

Lightmeter MCP lets AI agents interact with your Lightmeter account and outbound campaign workspaces using your regular Lightmeter login. All actions are tracked (labelled 'MCP') and visible in the Activity Log of your account.

Get setup by searching for the 'Lightmeter' app in ChatGPT or Codex, or pointing your AI agent at this documentation page, which contains all the info required for the agent to gain access.

Server Endpoint

Each MCP POST request is limited to 64 MiB, including any batch envelope. Send Revenue reads in a separate request from other tools; mixed batches are rejected before any tool runs.

Connection Details

Available Tools

Native agreement tools use a user-bound access_id. Open the linking page returned by onboarding_native_agreement_get, sign in with the same account as your assistant, and connect the invitation privately. Email codes stay on that page. Linked access retains the invitation's original or representative scope and can be disconnected there. Checkout and payment confirmation keep their existing original-contact restrictions. The public invitation API remains available with its existing browser capability contract.

Workspace credential actions use the same browser-completion workflow in every MCP client. A result with status: user_action_required means the requested change is still pending: open the returned authenticated settings page, complete the action there, then use metadata readers to inspect the saved configuration. Confirm secret rotation or private setup-link creation in the browser. These eight tools accept workspace_id only, plus provider for CRM; legacy payload and resource arguments are rejected. They retain the write OAuth scope and the existing workspace permission requirements even though the handoff call itself makes no change. Never paste API keys, CRM credentials or private setup links into a conversation. The public API and browser retain their existing credential contracts.

Connected clients can use these tools after you authorize access.

Binding agreement acceptance, Checkout creation/recovery and payment reconciliation are available through the existing website and API, not MCP. This restriction applies to the shared MCP catalog for every client. MCP retains agreement and payment status reads, exact document access and existing paid-service operations; it does not return a payment handoff link.

The detailed deliverability, speed-to-lead, and Revenue MCP report tools return a complete structured result capped at 128 KiB, including the summary and workspace metadata. An oversized result returns an error; the public report API provides the full response for organization API-key clients. OAuth-only MCP clients cannot continue a rejected unpaged report. Date filters can reduce some detailed views and the speed-to-lead report; the detailed campaigns view remains unpaged.

Choose Shared Campaign Infrastructure

All workspace users can use these tools. Call campaign_infrastructure_sharing_preview for the source campaign when creating a draft, or the destination when assigning mailboxes. Review the named campaigns and warnings before setting share_infrastructure=true for creation or allow_shared_infrastructure=true for assignment. Supply the returned review_fingerprint as infrastructure_sharing_review_fingerprint, and set acknowledge_shared_infrastructure_risks=true only after the user deliberately accepts those risks. A stale review is rejected; refresh before applying again.

Campaigns sharing a domain share its reputation: spam complaints in one can affect the others, even with different mailboxes. Campaigns sharing a physical mailbox share its limits, cooldown and pacing, so concurrent sending can slow the original campaign. Sharing adds no capacity, launches no campaign, and provides no automatic sequential handoff. Keep a new draft or a paused campaign stopped until you deliberately launch or resume it. Sequential use still shares domain reputation.

Sharing mutation requests are limited to 1 MiB. Moving leads changes source participation; follow-up retains it. Draft creation is not idempotent: if its response is lost, inspect campaigns before retrying. Existing calls to campaign_duplicate without sharing options keep creating unsent drafts without source mailboxes. New or changed tool definitions may take time to appear in a directory client while its provider reviews metadata; a custom connection reads the deployed server's current tools.

Adding blocklist values

Call workspace_blocklist_values_add with workspace_id, type (email or domain), and 1–500 values. MCP uses your signed-in role; workspace owners and admins can add blocks, and Lightmeter staff can manage workspaces they can access. Each call is limited to 256 KiB of arguments. Use separate calls for email addresses and domains.

The result reports each input position and its canonical value. A repeat call returns duplicate for an active block. Invalid values are reported individually while valid values are added. This blocks future sends across the workspace; it does not change lead subscription status or reopen leads previously skipped by a campaign. The same operation is available to API-key clients at POST /api/v1/blocklists/values.

Use workspace_blocklist_values_list for readback and workspace_blocklist_values_remove to reverse a block. The list returns at most 200 values per page. Removal accepts 1–500 values and is limited to 256 KiB of arguments; a repeated removal reports not_found. Both tools use the same workspace role rule as add, and API-key clients have matching public API operations.

For CSV, call workspace_blocklist_import_preview and then workspace_blocklist_import_apply with the same workspace_id, type, and csv text. Each tool accepts at most 2,000 rows and 1 MiB of arguments. Preview is read-only; apply adds inactive blocks in one transaction. Use workspace_blocklist_values_export with limit and each returned next_cursor to assemble a bounded CSV export. Keep the original filters for every page. Each page includes a header and can be imported separately; to combine pages, retain the first header and append only data rows from later pages. If a result exceeds 128 KiB, retry that page with a smaller limit. If limit=1 still exceeds the bound, use the public API CSV stream for that workspace. Signed-in owner/admin access is required for all three.

Applying Unibox lead actions

Call unibox_thread_lead_unsubscribe, unibox_thread_lead_email_blocklist, or unibox_thread_lead_domain_blocklist with an active workspace_id and canonical thread_id UUID. Your signed-in role must be workspace owner or admin, or Lightmeter staff. Each tool accepts up to 4 KiB of arguments.

Unsubscribe updates the campaign lead, records unsubscribe activity, and blocks its email. Blocklist actions only block the email or domain. Repeated calls do not duplicate an active block. API-key clients can use the same Unibox public API contract.

Campaign Lifecycle

Use lifecycle tools instead of attempting to write raw campaign status values. campaigns_list accepts either exact status or one of the broad lifecycle_scope values below, never both. Use status=active for the exact sending-enabled subset. Omit both to list all nondeleted campaigns.

1. Call campaign_lifecycle_get and use its identity-aware available_actions rather than assuming an action from a status label.
2. Generate one operation UUID for a write. Reuse it only when retrying the same logical command after an ambiguous outcome.
3. After campaign_end, poll campaign_lifecycle_get until the campaign leaves ending. Match pending_operation.id to the command's operation UUID while shutdown is in progress. Ending and ended campaigns accept no future sends or lead additions; unfinished leads are held as paused for reviewed recovery.
4. Use campaign_fast_forward only when it appears in available_actions. It is distinct from End: it may send at most one next queued message to each eligible lead, then completes the remaining leads and campaign, and cannot be undone.
5. Use campaign_reopen to move ended or completed to paused with reason reopened_for_review. The command preserves campaign data and never resumes sending. Add new leads only after a completed campaign has been reactivated.
6. If recovery is offered, preview the complete paused-lead plan. For each entry in continuity_requirements, choose an eligible replacement for the previous mailbox used on earlier campaign emails, then apply the unchanged plan with the returned review token. Sending campaigns (returned as lifecycle status active) continue sending other eligible leads; paused campaigns require a separate Resume command. Leads awaiting email verification wait individually and do not block Resume; unsendable leads remain excluded. A stale plan is rejected atomically.
7. If the current mailbox-change obligation will be handled later, use campaign_paused_lead_recovery_defer with the exact obligation ID and revision plus a nonblank reason. Deferral applies only to the affected paused leads; unrelated paused leads can still block Resume.
8. Resume remains a separate full-readiness operation. Authenticated workspace users and public API keys may invoke it for their workspace; readiness failures leave the campaign Paused.

Lead Import and Enrichment

The lead import tools mirror the Leads API. They create valid missing leads by default and preserve existing standard and custom attribute values by default. This makes enrichment additive unless you deliberately select overwrite, preview the exact replacements, and confirm them during apply.

Workspace lead management tools share the same workspace-scoped browser handlers for listing, reply history, CSV import, history, and undo. CSV MCP tools accept UTF-8 text in csv_content, up to 10 MiB and 10,000 rows. Review the impact before apply; CSV apply requires unchanged expected_impact and an operation_id UUID for safe retry. Campaign assignments in CSV are outside this workspace import path.

1. Inventory the complete source before chunking and require one non-empty, stable source_ref per row. Report every missing or repeated ref as a detailed client preflight failure, exclude those rows, and keep unrelated valid rows. Then split the remainder into stable chunks of at most 2,000 records.
2. Before previewing any chunk, inventory all audience definitions, defaults, and each lead's effective refs across the complete source. Require one identical definition for each audience ref, at most 100 distinct audience refs across one logical import, and at most 10,000 lead-to-audience assignment edges across that complete source. Count unique (source_ref, effective audience ref) pairs after per-lead overrides. If either complete-source limit is exceeded, do not preview or apply any chunk.
3. Call workspace_leads_import_preview for every chunk before applying any chunk. The first preview using an audience ref returns its plan_token; include that same ref, definition, and token in every later preview that uses it.
4. Combine each preview item's returned identity_refs and resolved lead_id into transitive components across the whole source. Stop without applying anything if a component spans chunks; repartition every row in that component into one chunk, then preview the complete source again. This catches indirect overlaps such as one row containing identity A, another A and X, and another X.
5. Review failed rows, protected values, planned replacements, and audience effects.
6. Repeat the unchanged input with the returned review_token, every returned audience plan_token, and a new operation_id in workspace_leads_import_apply.
7. Keep one operation UUID per chunk and reuse it only when retrying an ambiguous outcome. A recovered response returns the original committed result without duplicating history.

You may use default_audience_refs for the common case and override them with per-lead audience_refs, so one operation can put different leads into different audiences. Include only the audience definitions used by each chunk; later chunks repeat the same definition and first preview's plan_token. An explicit empty per-lead audience_refs array opts that lead out. Membership is additive and does not remove existing memberships.

Preview Example

Creative Writeback

Call campaign_creative_get first. It always returns target-labelled Creative documents, including inactive adaptation history, and separately reports the server-owned adaptations_activated capability. That value is not a client request flag or response filter. Non-Default writes are enabled only when it is exactly true; when false, do not present an Adapt action or send adaptation_target or adaptation_active.

When adaptation capability is enabled, campaign_creative_update can save sparse adaptations for Google, Microsoft, and SEGs. Omitting adaptation_target makes only that submitted field Default; it does not conceal other adaptations from Get. A target-specific subject or body can be adapted independently; every missing target field inherits Default. Omitting adaptation_active preserves an existing adaptation's lifecycle state, while true explicitly reactivates it. An update does not approve content or change the Ready snapshot. campaign_creative_approve always approves Default and includes active adaptations only while the capability is enabled.

For AI-assisted drafting, call campaign_creative_generation_capability_get to read the current revision and quota, then campaign_creative_generate with a fresh operation UUID, audience, offer, and one text or base64 PDF source. Generation consumes included quota and returns a transient draft; it does not save or send. Use campaign_creative_generated_draft_apply with the returned draft and revision to replace the working copy, then approve separately when ready. The completed operation ID cannot replay the transient draft.

campaign_creative_workspace_get returns current documents, checkpoints, comment threads, and the workspace revision. campaign_creative_checkpoint_create saves manual document checkpoints; campaign_creative_checkpoint_restore restores one with the expected revision. campaign_creative_snapshots_list lists retained recovery snapshots; campaign_creative_snapshot_restore requires the expected current revision and creates a pre-restore snapshot. Use campaign_creative_comment_add, campaign_creative_comment_reply, campaign_creative_comment_resolve, campaign_creative_comment_reopen, and campaign_creative_comment_delete for agent-attributed review comments and thread cleanup. Browser cursor presence and real-time editing leases remain in the signed-in UI collaboration protocol.

Update Example When adaptations_activated Is True

Reset One Adaptation to Default When adaptations_activated Is True

• variant_number starts at 1; the app may display that as Variant A.
• subject_number orders subjects within one body variant. Omit it for Subject 1; body documents always use 1. After an update, each subject set must be contiguous from 1 with no gaps. A complete batch may list those numbered subjects in any array order. Up to 26 subjects are accepted.
• field_type must be subject or body.
• Use adaptation_target only after campaign_creative_get returns adaptations_activated=true. It accepts google_workspace, microsoft_365, or seg; omit it for Default. There is no Other adaptation because Other, Unknown, and unmanaged routes use Default.
• When adaptation capability is enabled, adaptation_active=false is an idempotent, recoverable reset. It retains target history while the effective field inherits Default. Use true to explicitly reactivate changed content. Omitting the field creates a new adaptation as active but preserves an existing adaptation's lifecycle state. Content exactly equal to Default also collapses to inheritance without creating redundant target content.
• Threading and subject or variant eligibility belong to Default. Adaptations inherit those controls, and threaded follow-ups cannot adapt their inherited parent subject.
• For a subject document, optional is_disabled plans whether it will be eligible when the working copy is approved and marked Ready. Omitting it preserves an existing subject's planned state and enables a new subject by default.
• When is_threaded is true, the step replies to the previous step and subject text is cleared for that threaded step.
• Updating an existing Creative field requires overwrite_existing=true; first-time imports into empty fields do not.
• Approving a new final step on an active or completed campaign may require extension_behavior: append_only or append_and_reconcile.
• For an already-approved follow-up, explicitly choose append_and_reconcile to reopen eligible completed leads on an Active, Paused, or Completed campaign. Repeating continuation preserves prior sends and sender affinity; replied and other terminal leads remain excluded.
• Subject metrics are directional evidence. Compare absolute counts, combined End-autoreply rate, human replies, and positive replies before deciding what to enable or disable.

Related Documentation

• Lightmeter API catalog
• Campaigns API documentation
• Leads API documentation
• Unibox API documentation
• Analytics API documentation
• Product documentation