Lightmeter MCP
Remote MCP server for Lightmeter outbound campaign workspaces
Remote MCP server for Lightmeter outbound campaign workspaces
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.
OAuth sign-in with your Lightmeter account. You do not need to copy or store an API key.
MCP can access all workspaces that your Lightmeter login supports.
| Field | Value |
|---|---|
| Display name | Lightmeter |
| Server URL | https://mcp.lightmeter.io/mcp |
| Authentication | OAuth sign-in with your Lightmeter account |
Connected clients can use these tools after you authorize access.
| Tool | Purpose |
|---|---|
workspaces_list |
List workspaces available to the signed-in account. |
campaigns_list |
List campaigns in a workspace, with filters for status, search, deletion state, and completion deadline state. |
campaigns_get |
Retrieve one campaign, its sequence details, canonical lifecycle projection, and identity-aware related actions. |
campaign_lifecycle_get |
Retrieve canonical status, pause reason, identity-aware available actions, sendability and readiness blockers, and any pending lifecycle operation. |
campaign_pause |
Pause an active campaign using a client-generated operation UUID. |
campaign_resume |
Resume a paused campaign after full readiness checks. Available to authenticated workspace users. |
campaign_end |
Deliberately stop an active or paused campaign, then poll lifecycle state until ending becomes ended. |
campaign_fast_forward |
Send at most the next queued message to each eligible lead, then complete an eligible campaign. Available while sending is enabled and at least 95% complete. |
campaign_reopen |
Reopen an ended campaign or reactivate a completed campaign into paused review without changing lead states, mailbox assignments, history, replies, or results. This never resumes sending. |
campaign_paused_lead_recovery_preview |
Preview the complete all-or-nothing recovery plan for paused leads on a Sending (lifecycle status active) or Paused campaign. Sending recovery is limited to the current mailbox-change obligation. For leads that already received campaign emails, the response's continuity_requirements reports each previous mailbox, affected leads, remaining campaign emails, required recipient mailbox-host sending pools, eligible replacement mailboxes, and exact ineligibility reasons. |
campaign_paused_lead_recovery_apply |
Apply an unchanged reviewed recovery plan atomically while preserving the campaign's Sending (lifecycle status active) or Paused status. Resume is a separate command. |
campaign_paused_lead_recovery_defer |
Explicitly defer the current mailbox-change recovery obligation with a required reason and the exact obligation ID and revision from lifecycle state or preview. The campaign's status is preserved; Resume is a separate command. |
campaign_creative_get |
Retrieve target-labelled Default Creative, every sparse adaptation document including inactive history, step settings, and the server-owned adaptations_activated capability. It is not a request flag or response filter; non-Default writes require it to be exactly true. |
campaign_creative_update |
Write Default Creative and optionally update Default-owned step settings. When adaptations_activated is exactly true, the tool can also Adapt sparse fields for Google, Microsoft, and SEGs or reset an adaptation to inherit Default. Existing fields require overwrite_existing=true. |
campaign_creative_approve |
Approve Default Creative as an immutable snapshot and mark it Ready for future sends. When the server-owned adaptations_activated capability is exactly true, the snapshot also includes all active sparse adaptations; inactive history remains visible through Get. |
campaign_subject_pause_set |
Enable or disable one current subject on the Ready Creative without editing or reapproving its shared body. At least one subject for the body remains enabled. |
campaign_analytics_lifetime_get |
Retrieve lifetime totals, rates, rate context, and drilldowns for one campaign. |
campaign_analytics_timeseries_get |
Retrieve date-grained campaign analytics by day, week, month, or total. |
campaign_analytics_sequence_get |
Retrieve date-grained performance by step, shared-body variant, and stable subject revision, including its source Creative document ID when available, current enabled or disabled state, and retired history with sends. |
campaign_analytics_leads_list |
List lead-level campaign analytics with sorting and pagination. |
campaign_lead_activity_list |
List chronological activity for one campaign lead. |
campaign_replies_list |
List qualified human reply excerpts and classifications for a campaign and date range. |
unibox_threads_list |
List Unibox threads with filters for answer status, campaign, mailbox, conversation classification, reply primary category, and reply subcategory. |
unibox_thread_get |
Retrieve one Unibox thread with chronological messages, current answer status, classification evidence, and reply context. |
unibox_thread_reply_send |
Send a validated plaintext reply from a workspace mailbox identity with stale-message checks, sender validation, idempotency, and rate-limit feedback. |
campaign_lead_quality_diagnostics_get |
Retrieve lead-quality diagnostics for a campaign, including email verification counts and unavailable signals. |
workspace_analytics_overview_get |
Retrieve workspace-level analytics for a date range. |
workspace_report_summary_get |
Retrieve the workspace summary report for a date range. |
workspace_report_campaigns_get |
Retrieve the workspace campaigns report. |
workspace_report_campaign_performance_get |
Retrieve campaign performance segmentation from the reports surface. |
workspace_report_engagement_performance_get |
Retrieve engagement performance trends for a date range. |
workspace_report_engagement_reply_breakdown_get |
Retrieve categorized reply breakdowns and examples for a date range. |
workspace_report_deliverability_get |
Retrieve deliverability, list quality, bounce, and box-host report data for a date range. |
workspace_report_volume_get |
Retrieve volume, planned capacity, and utilization report data for a date range. |
workspace_report_stocks_get |
Retrieve current lead stock and runway report data. |
campaign_send_timeline_get |
Retrieve the campaign send timeline projection shown in the campaign editor, including campaign-timezone completion instants when available.
At the response root and on each steps item, provider_acceptance_timing_basis identifies the provider_acceptance_at_projected_handoff_v1 calculation when present: simulated sends are assumed accepted by their mailbox's sending service at the projected handoff instant, and projected rolling-window expiry is calculated from that instant.
provider_acceptance_timing_dependent is true exactly when that object's projected milestones rely on the calculation, including a step that inherits the timing from an earlier step in the same lead chain.
provider_acceptance_timing_first_used_at is the earliest projected RFC3339 instant at which the calculation influences that object and is omitted when dependency is false.
Future capacity assumes prompt confirmation from each mailbox's sending service. Delays can move the projection later.
|
campaigns_submit |
Create a draft campaign for review. Use preview_only to inspect existing lead corrections before creating it, then apply with the returned review token and any required preserve/overwrite decision. Inspect row_outcomes for partial success. See campaign import review. The result uses campaign_status=draft; legacy status=created describes the completed create operation. |
workspace_leads_import_preview |
Preview creation, protected or replaced standard and custom attributes, invalid rows, and optional audience assignments for up to 250 structured leads. |
workspace_leads_import_apply |
Apply the unchanged reviewed lead import with a client-generated operation UUID. Explicit confirmation is required when the selected policies replace existing values. |
campaign_leads_add |
Add leads to an existing campaign, with a read-only import review and per-row outcomes. Use preview_only, then the returned review_token and an explicit decision for changes shared with other unfinished campaigns. See campaign import review. |
Creative MCP tools follow the same contract as the Campaigns API Creative endpoints. Use MCP when you want OAuth sign-in through a connected client; use the public API directly when you want API-key access.
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.
| Lifecycle scope | Included statuses |
|---|---|
unfinished |
draft, submitted, active, paused, and ending |
finished |
completed and ended |
all |
Every supported nondeleted lifecycle state, including legacy archived campaigns |
campaign_lifecycle_get and use its identity-aware available_actions rather than assuming an action from a status label.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.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.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.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.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.Replacement mailbox diagnostics: A requirement's remaining_send_count counts one campaign email for each distinct future sequence step after each affected lead's current step that has at least one runtime-sendable variant. A threaded variant remains sendable even when marked paused; a non-threaded variant must be unpaused. Each sending pool's mailbox_count counts current campaign assignments before health and eligibility filtering; eligible_replacement_mailbox_count counts mailboxes that pass every health check and belong to every required pool. Ineligible mailboxes include exact ineligibility_reasons: mailbox_not_found, mailbox_inactive, mailbox_domain_inactive, mailbox_lifecycle_missing, mailbox_lifecycle_not_in_use, not_in_required_sender_pool, or not_assigned_to_campaign.
Sendable describes eligibility for future sends under the current lifecycle state. It does not promise that a provider will accept or deliver a message. Deliverable remains reserved for analyzed email-address classification and deliverability reporting.
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.
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 250 records.(source_ref, effective audience ref) pairs after per-lead overrides. If either complete-source limit is exceeded, do not preview or apply any chunk.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.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.review_token, every returned audience plan_token, and a new operation_id in workspace_leads_import_apply.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.
Omitting an attribute leaves it untouched. This version does not clear attributes with null or an empty string. Each MCP call accepts at most 250 rows and 1 MiB of encoded arguments, and its complete result is limited to 128 KiB. The stable arguments_too_large and result_too_large errors mean you must repartition the source into smaller deterministic chunks and preview every chunk again before any apply. Use the public API directly when a logical import must contain more than 250 records in one transaction; the API accepts up to 2,000.
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.
adaptations_activated Is Trueadaptations_activated Is Truevariant_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.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.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.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.is_threaded is true, the step replies to the previous step and subject text is cleared for that threaded step.overwrite_existing=true; first-time imports into empty fields do not.extension_behavior: append_only or append_and_reconcile.