Campaign Management
The Campaigns API lets connected tools submit campaigns, add leads, list campaigns, and inspect campaign configuration using your Organization API Key.
Create campaigns
Submit a campaign with leads, sending schedule, and automated email sequence steps.
Add leads
Add leads to an existing campaign while applying the same dedupe and validation rules.
Inspect configuration
List campaigns and retrieve individual campaign details before taking action.
Base URL and Authentication
All requests use the standard bearer token header.
https://beam.lightmeter.io
Authorization: Bearer your_api_key_here
Example Request
POST
/api/v1/campaigns/submit
curl -X POST https://beam.lightmeter.io/api/v1/campaigns/submit \
-H "Authorization: Bearer your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"campaign_name": "Product Launch Outreach",
"schedule": {
"timezone": "America/New_York",
"days": ["Mon", "Tue", "Wed", "Thu", "Fri"],
"daily_start_time": "09:00",
"daily_end_time": "17:00"
},
"lead_dedupe_scope": "all_campaigns",
"leads": [
{
"email": "contact@example.com",
"first_name": "Alex",
"last_name": "Johnson",
"company_name": "TechCorp Inc",
"contact_linkedin_url": "https://linkedin.com/in/alexjohnson",
"account_linkedin_url": "https://linkedin.com/company/techcorp",
"timezone": "Pacific Standard Time",
"attributes": {
"job_title": "VP of Engineering",
"industry": "Technology",
"custom_note": "Interested in automation tools"
}
}
],
"sequence": [
{
"step": 1,
"type": "new",
"variants": [
{
"subject": [
"Quick question for {{first_name}}",
"An idea for {{company_name}}",
"Worth comparing notes?",
"One practical question"
],
"body": "Hi {{first_name}}, I noticed your recent work at {{company_name}}..."
}
]
}
]
}'
Key Validation Rules
- Schedule: valid IANA timezone, unique days, HH:MM time format, and start time before end time.
- Leads: no duplicate emails; LinkedIn URLs must start with
http:// or https:// and contain linkedin.com.
- Attributes: keys must be alphanumeric with
_ or - only, up to 100 characters. Reserved keys include id, customer_id, email, first_name, last_name, company, company_name, linkedin_url, timezone, created_at, and updated_at.
- Sequence: steps must be sequential with no gaps or duplicates.
- Variants: variants are labeled by array position. A new-message variant can have up to 26 ordered subject options above one shared body. Enabled subjects are selected uniformly; threaded follow-ups inherit the parent subject and support one body variant.
- Dedupe policy: optional
lead_dedupe_scope must be none, active_campaigns, all_campaigns, or all_audiences. Omitted or empty values default to none.
- Completion deadline: requests may send an exact RFC3339 timestamp, or a legacy
YYYY-MM-DD value when a valid campaign timezone is included in the schedule. Responses keep completion_deadline as date-only for compatibility and expose the exact stored cut-off in completion_deadline_at.
- Workspace suppression: explicit unsubscribe replies add the recipient email to the workspace email blocklist. Remove that blocklist entry before intentionally contacting the recipient again from a future campaign.
Prepare the Creative Working Copy
Use the Creative endpoints to save one or more numbered subjects above each shared body, plus planned subject eligibility, variants, step delays, and threading settings before approval. Updating Creative saves immutable snapshot history but does not change the Ready Creative used for future sends.
PUT
/api/v1/campaigns/{campaign_id}/creative
curl -X PUT https://beam.lightmeter.io/api/v1/campaigns/550e8400-e29b-41d4-a716-446655440000/creative \
-H "Authorization: Bearer your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"overwrite_existing": true,
"documents": [
{
"step_number": 1,
"variant_number": 1,
"field_type": "subject",
"subject_number": 1,
"plain_text": "Quick question for {{first_name}}"
},
{
"step_number": 1,
"variant_number": 1,
"field_type": "subject",
"subject_number": 2,
"is_disabled": true,
"plain_text": "An idea for {{company_name}}"
},
{
"step_number": 1,
"variant_number": 1,
"field_type": "body",
"subject_number": 1,
"plain_text": "Hi {{first_name}}, noticed your work at {{company_name}}..."
}
],
"step_settings": [
{
"step_number": 2,
"wait_days": 3,
"is_threaded": true
}
]
}'
Creative Approval
Call POST /api/v1/campaigns/{campaign_id}/creative/approve when the current Creative working copy should become an immutable approved snapshot and be marked Ready for future sends. Existing Creative fields are protected from accidental overwrite unless overwrite_existing is true. New subject numbers must leave each body with a contiguous set starting at 1; one request may provide a complete batch in any array order. Optional is_disabled on subject documents plans eligibility for the next Ready Creative. Use PATCH /api/v1/campaigns/{campaign_id}/subjects/{subject_id} to change one current Ready subject without editing or reapproving the shared body.
