Campaigns API

Email, SMS and WhatsApp campaigns to your customers, with opens and clicks.

Module code campaigns · 16 actions · 7 data models · 12 events. A key or token never does more here than the person behind it can; row-level security applies exactly as in the app. Scopes: campaigns (everything), campaigns:read (read only) or campaigns:<capability>.

Resources

Lists take limit (up to 200), cursor, order (e.g. -created_at), fields and q; every other query parameter is a column filter: ?status=paid, ?total[gte]=100, ?id[in]=a,b, ?x=null.

Actions

campaigns.cancel

Stop sending — Stops a scheduled or sending campaign; whoever has not been sent to yet is not.

Needs campaigns:write · removes or cannot be undone · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/campaigns.cancel

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: campaigns.cancelled

What it writes: campaign (update) — Marks it cancelled; campaign_recipient (update) — Skips those not yet sent to

curl -X POST https://app.getera.io/api/v1/campaigns/CAMPAIGN_ID/actions/cancel \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "campaigns.cancelled"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.campaigns.cancel("CAMPAIGN_ID")

era campaigns cancel CAMPAIGN_ID

{
  "name": "era__campaigns__cancel",
  "arguments": {
    "id": "CAMPAIGN_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold campaigns:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 campaign_not_found, campaign_not_cancellable · 429 slow down

campaigns.create

Draft a campaign — An email, SMS or WhatsApp message to an audience, drafted to be tested, scheduled and sent.

Needs campaigns:write · changes data

• REST alias: POST /api/v1/campaigns
• Canonical address: POST /api/v1/actions/campaigns.create

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: campaigns.created

What it writes: campaign (insert) — Writes the draft

curl -X POST https://app.getera.io/api/v1/campaigns/actions/create \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name":"Name","audienceId":"AUDIENCE_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "campaigns.created"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.campaigns.create({
  name: "Name",
  audienceId: "AUDIENCE_ID"
})

era campaigns create \
  --name "Name" \
  --audience-id "AUDIENCE_ID"

{
  "name": "era__campaigns__create",
  "arguments": {
    "name": "Name",
    "audienceId": "AUDIENCE_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold campaigns:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 audience_not_found, invalid_campaign_blocks · 429 slow down

campaigns.create_audience

Create an audience — A saved segment of customers: their fields, their tags, whether they are a lead, and what they bought or booked.

Needs campaigns:write · changes data

• REST alias: POST /api/v1/audiences
• Canonical address: POST /api/v1/actions/campaigns.create_audience

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: campaigns.audience_changed

What it writes: audience (insert) — Saves the segment

curl -X POST https://app.getera.io/api/v1/audiences/actions/create_audience \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name":"Name"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "campaigns.audience_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.audiences.create({
  name: "Name"
})

era audiences create \
  --name "Name"

{
  "name": "era__campaigns__create_audience",
  "arguments": {
    "name": "Name"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold campaigns:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 invalid_audience_rules · 429 slow down

campaigns.delete

Delete a draft campaign — Removes a campaign that was never sent.

Needs campaigns:delete · removes or cannot be undone · asks a person to confirm when Era runs it

• REST alias: DELETE /api/v1/campaigns/{id}
• Canonical address: POST /api/v1/actions/campaigns.delete

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: campaigns.deleted

What it writes: campaign (delete) — Deletes the draft

curl -X POST https://app.getera.io/api/v1/campaigns/CAMPAIGN_ID/actions/delete \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "campaigns.deleted"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.campaigns.delete("CAMPAIGN_ID")

era campaigns delete CAMPAIGN_ID

{
  "name": "era__campaigns__delete",
  "arguments": {
    "id": "CAMPAIGN_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold campaigns:delete · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 campaign_not_found, campaign_not_draft · 429 slow down

campaigns.delete_audience

Delete an audience — Removes a segment no campaign uses.

Needs campaigns:delete · removes or cannot be undone · asks a person to confirm when Era runs it

• REST alias: DELETE /api/v1/audiences/{id}
• Canonical address: POST /api/v1/actions/campaigns.delete_audience

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: campaigns.audience_changed

What it writes: audience (delete) — Deletes the segment

curl -X POST https://app.getera.io/api/v1/audiences/AUDIENCE_ID/actions/delete_audience \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "campaigns.audience_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.audiences.deleteAudience("AUDIENCE_ID")

era audiences delete_audience AUDIENCE_ID

{
  "name": "era__campaigns__delete_audience",
  "arguments": {
    "id": "AUDIENCE_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold campaigns:delete · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 audience_not_found, audience_in_use · 429 slow down

campaigns.record_batch

Record a sent batch — Machine-only (campaigns-jobs.ts): which recipients were handed to the sender and which were skipped.

Needs campaigns:handle · changes data

• Canonical address: POST /api/v1/actions/campaigns.record_batch

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: campaigns.batch_recorded, campaigns.sent

What it writes: campaign_recipient (update) — Queued or skipped; campaign (update) — Sent when nobody is left

Errors: 401 no or expired credential · 403 the credential does not hold campaigns:handle · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 campaign_not_found, invalid_batch · 429 slow down

campaigns.resubscribe

Take off the unsubscribe list — For a person who asked to hear from you again.

Needs campaigns:manage · removes or cannot be undone · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/campaigns.resubscribe

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: campaigns.resubscribed

What it writes: marketing_unsubscribe (delete) — Removes the address

curl -X POST https://app.getera.io/api/v1/marketing_unsubscribes/actions/resubscribe \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"email":"Email or phone"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "campaigns.resubscribed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.marketingUnsubscribes.resubscribe({
  email: "Email or phone"
})

era marketing_unsubscribes resubscribe \
  --email "Email or phone"

{
  "name": "era__campaigns__resubscribe",
  "arguments": {
    "email": "Email or phone"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold campaigns:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 unsubscribe_not_found · 429 slow down

campaigns.resubscribe_me

Send me campaign messages again — A signed-in customer turns campaign emails and texts back on from their site account.

Needs campaigns:write · removes or cannot be undone · Also callable from a published site (customer)

• Canonical address: POST /api/v1/actions/campaigns.resubscribe_me

Input

This action takes no input.

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: campaigns.resubscribed

What it writes: marketing_unsubscribe (delete) — Their own address off the list

Errors: 401 no or expired credential · 403 the credential does not hold campaigns:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 no_contact_on_record, unsubscribe_not_found · 429 slow down

campaigns.schedule

Schedule or send — Sends at the chosen time, or now; it goes out in batches through notifications.

Needs campaigns:write · reaches outside (sends, publishes or charges) · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/campaigns.schedule

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: campaigns.scheduled

What it writes: campaign (update) — Marks it scheduled

curl -X POST https://app.getera.io/api/v1/campaigns/CAMPAIGN_ID/actions/schedule \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"sendAt":"2026-11-02T09:00:00Z"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "campaigns.scheduled"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.campaigns.schedule("CAMPAIGN_ID", {
  sendAt: "2026-11-02T09:00:00Z"
})

era campaigns schedule CAMPAIGN_ID \
  --send-at "2026-11-02T09:00:00Z"

{
  "name": "era__campaigns__schedule",
  "arguments": {
    "id": "CAMPAIGN_ID",
    "sendAt": "2026-11-02T09:00:00Z"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold campaigns:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 campaign_not_found, campaign_not_draft, campaign_incomplete, campaign_no_channel, audience_empty · 429 slow down

campaigns.send_test

Send a test — One copy to one address, through the same email channel the campaign will use — the designed email as it goes out.

Needs campaigns:write · reaches outside (sends, publishes or charges)

• Canonical address: POST /api/v1/actions/campaigns.send_test

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: campaigns.test_requested

What it writes: campaign (update) — Stamps when a test last went

curl -X POST https://app.getera.io/api/v1/campaigns/CAMPAIGN_ID/actions/send_test \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"to":"Send to"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "campaigns.test_requested"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.campaigns.sendTest("CAMPAIGN_ID", {
  to: "Send to"
})

era campaigns send_test CAMPAIGN_ID \
  --to "Send to"

{
  "name": "era__campaigns__send_test",
  "arguments": {
    "id": "CAMPAIGN_ID",
    "to": "Send to"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold campaigns:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 campaign_not_found, invalid_recipient · 429 slow down

campaigns.start

Start a due campaign — Machine-only (campaigns-jobs.ts): lists the recipients, registers the links to track, and starts sending.

Needs campaigns:handle · changes data

• Canonical address: POST /api/v1/actions/campaigns.start

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: campaigns.started, campaigns.sent

What it writes: campaign_recipient (insert) — One row per address; campaign_link (insert) — One row per link in the email, for click tracking; campaign (update) — Marks it sending

Errors: 401 no or expired credential · 403 the credential does not hold campaigns:handle · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 campaign_not_found, campaign_not_due · 429 slow down

campaigns.unschedule

Back to draft — Takes a scheduled campaign back to a draft before it starts.

Needs campaigns:write · changes data

• Canonical address: POST /api/v1/actions/campaigns.unschedule

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: campaigns.updated

What it writes: campaign (update) — Back to draft

curl -X POST https://app.getera.io/api/v1/campaigns/CAMPAIGN_ID/actions/unschedule \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "campaigns.updated"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.campaigns.unschedule("CAMPAIGN_ID")

era campaigns unschedule CAMPAIGN_ID

{
  "name": "era__campaigns__unschedule",
  "arguments": {
    "id": "CAMPAIGN_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold campaigns:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 campaign_not_found, campaign_not_scheduled · 429 slow down

campaigns.unsubscribe

Unsubscribe an address — Puts an address or phone number on the unsubscribe list — from the message’s link, or by a member on request.

Needs campaigns:write · changes data · Also callable from a published site (visitor)

• Canonical address: POST /api/v1/actions/campaigns.unsubscribe

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: campaigns.unsubscribed

What it writes: marketing_unsubscribe (insert) — Adds the address to the list

Errors: 401 no or expired credential · 403 the credential does not hold campaigns:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 unsubscribe_link_invalid, unsubscribe_link_required, invalid_recipient · 429 slow down

campaigns.unsubscribe_me

Stop campaign messages to me — A signed-in customer turns off campaign emails and texts from their site account.

Needs campaigns:write · changes data · Also callable from a published site (customer)

• Canonical address: POST /api/v1/actions/campaigns.unsubscribe_me

Input

This action takes no input.

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: campaigns.unsubscribed

What it writes: marketing_unsubscribe (insert) — Their own address on the list

Errors: 401 no or expired credential · 403 the credential does not hold campaigns:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 no_contact_on_record, already_unsubscribed · 429 slow down

campaigns.update

Edit a campaign — Changes a draft’s name, channel, subject, message, email blocks or audience.

Needs campaigns:write · changes data

• REST alias: PATCH /api/v1/campaigns/{id}
• Canonical address: POST /api/v1/actions/campaigns.update

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: campaigns.updated

What it writes: campaign (update) — Rewrites the draft

curl -X POST https://app.getera.io/api/v1/campaigns/CAMPAIGN_ID/actions/update \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name":"Name"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "campaigns.updated"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.campaigns.update("CAMPAIGN_ID", {
  name: "Name"
})

era campaigns update CAMPAIGN_ID \
  --name "Name"

{
  "name": "era__campaigns__update",
  "arguments": {
    "id": "CAMPAIGN_ID",
    "name": "Name"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold campaigns:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 campaign_not_found, campaign_not_draft, audience_not_found, invalid_campaign_blocks · 429 slow down

campaigns.update_audience

Edit an audience — Changes the segment’s name or rules. Campaigns already sent keep who they were sent to.

Needs campaigns:write · changes data

• REST alias: PATCH /api/v1/audiences/{id}
• Canonical address: POST /api/v1/actions/campaigns.update_audience

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: campaigns.audience_changed

What it writes: audience (update) — Rewrites the segment

curl -X POST https://app.getera.io/api/v1/audiences/AUDIENCE_ID/actions/update_audience \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name":"Name"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "campaigns.audience_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.audiences.updateAudience("AUDIENCE_ID", {
  name: "Name"
})

era audiences update_audience AUDIENCE_ID \
  --name "Name"

{
  "name": "era__campaigns__update_audience",
  "arguments": {
    "id": "AUDIENCE_ID",
    "name": "Name"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold campaigns:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 audience_not_found, invalid_audience_rules · 429 slow down

Data models

AudienceFact

Table audience_fact · Resource audience_facts

• GET /api/v1/audience_facts
• GET /api/v1/audience_facts/{id}

Primary key: id

Unique: workspace_id, kind, source_id

Checks:

• CHECK ((amount >= 0))
• CHECK (((currency IS NULL) OR (currency ~ '^[A-Z]{3}$'::text)))

Audience

Table audience · Resource audiences

• GET /api/v1/audiences
• GET /api/v1/audiences/{id}
• POST /api/v1/audiences → campaigns.create_audience
• PATCH /api/v1/audiences/{id} → campaigns.update_audience
• DELETE /api/v1/audiences/{id} → campaigns.delete_audience

Primary key: id

Checks:

• CHECK ((length(TRIM(BOTH FROM name)) > 0))
• CHECK ((jsonb_typeof(rules) = 'array'::text))

CampaignClick

Table campaign_click · Resource campaign_clicks

• GET /api/v1/campaign_clicks
• GET /api/v1/campaign_clicks/{id}

Primary key: id

CampaignLink

Table campaign_link · Resource campaign_links

• GET /api/v1/campaign_links
• GET /api/v1/campaign_links/{id}

Primary key: id

Unique: campaign_id, url

Checks:

• CHECK ((url ~* '^(https?://\|mailto:\|tel:)'::text))

CampaignRecipient

Table campaign_recipient · Resource campaign_recipients

• GET /api/v1/campaign_recipients
• GET /api/v1/campaign_recipients/{id}

Primary key: id

Unique: campaign_id, email

Checks:

• CHECK (((email IS NOT NULL) OR (phone IS NOT NULL)))

Campaign

Table campaign · Resource campaigns

• GET /api/v1/campaigns
• GET /api/v1/campaigns/{id}
• POST /api/v1/campaigns → campaigns.create
• PATCH /api/v1/campaigns/{id} → campaigns.update
• DELETE /api/v1/campaigns/{id} → campaigns.delete

Primary key: id

Checks:

• CHECK ((jsonb_typeof(blocks) = 'array'::text))
• CHECK ((length(TRIM(BOTH FROM name)) > 0))
• CHECK (((status <> 'scheduled'::text) OR (scheduled_at IS NOT NULL)))

MarketingUnsubscribe

Table marketing_unsubscribe · Resource marketing_unsubscribes

• GET /api/v1/marketing_unsubscribes
• GET /api/v1/marketing_unsubscribes/{id}

Primary key: id

Unique: workspace_id, email

Checks:

• CHECK (((email IS NOT NULL) OR (phone IS NOT NULL)))
• CHECK ((email = lower(email)))

Events

Workflows and webhooks react to these events.