API
Marketing
Settings, consent, lists, segments, content, campaigns, journeys, forms, landing pages and the public hooks.
See Marketing. Everything is read and changed as the caller: keys act as their maker, narrowed by the key's scopes. Scheduling, sending, publishing journeys and approving need marketing:send; settings, consent by hand and lifting a reputation pause need marketing:admin. Keys, MCP and Caity count against the organization's Marketing calls per minute.
The hooks under /v1/hooks/marketing need no sign-in: their tokens are sealed and say what they're for. Tracked links redirect only to the links of the message they came in.
Every route below, with its parameters, request and response, errors and samples, is in the API reference.
| Route | What it does |
|---|---|
GET /v1/hooks/marketing/c/:token | A tracked link: 302 to the send's link at that position (HEAD and scanners count as machine clicks). |
GET /v1/hooks/marketing/o/:token | The open pixel: always the image; bad or test tokens record nothing. |
POST /v1/hooks/marketing/u/:token | RFC 8058 one-click unsubscribe from everything (mail clients POST List-Unsubscribe=One-Click). |
GET /v1/hooks/marketing/u/:token | The footer's Unsubscribe link: the preference centre, ready to unsubscribe (a GET never changes anything). |
GET /v1/hooks/marketing/preferences/:token | The preference centre's address (masked), status and topics. |
POST /v1/hooks/marketing/preferences/:token | Saves the preference centre: a choice per topic, or unsubscribe from everything. |
POST /v1/hooks/marketing/confirm/:token | Double opt-in: the confirmation page's Confirm button (a POST, so mail scanners can't confirm). |
GET /v1/hooks/marketing/forms/:formId | A form as its page shows it, with a fresh ticket to send back. |
POST /v1/hooks/marketing/forms/:formId | A submission (values by field, the consent box, the ticket, the page and its query parameters). |
GET /v1/hooks/marketing/pages/:org/:slug | A published landing page with its forms; view=1 counts a view. |
GET /v1/orgs/:orgId/marketing/meta | What the app loads first: settings, brand kit, sending state and readiness, Mail domains, approvers, members, limits and what the caller may do. |
PUT /v1/orgs/:orgId/marketing/settings | Sender, physical address, topics, approvals, frequency cap, send-time default, UTM and double opt-in (Marketing admins), over version. |
PUT /v1/orgs/:orgId/marketing/brand | The brand kit marketing email is drawn in: logo, light and dark colours, font and corner radius (Marketing admins). |
POST /v1/orgs/:orgId/marketing/resume | Lifts the reputation guard's pause once the audience is cleaned (Marketing admins). |
GET /v1/orgs/:orgId/marketing/usage | Messages this month and today (the plan's month, warm-up's day) and the plan's limits. |
GET /v1/orgs/:orgId/marketing/stats/daily | The org's numbers per UTC day (from, to as YYYYMMDD; the last 30 days by default) and their totals. |
GET /v1/orgs/:orgId/marketing/people/:address | An address's consent, its history (newest first), its engagement summary and recent opens, clicks and unsubscribes. |
PUT /v1/orgs/:orgId/marketing/people/:address/consent | Sets an address's consent by hand with a note as the evidence (Marketing admins); subscribing clears a bounce or complaint. |
GET /v1/orgs/:orgId/marketing/lists | Static and suppression lists with their member counts. |
POST /v1/orgs/:orgId/marketing/lists | A static list (people added by hand, CSV or API) or a suppression list (never sent to), for email or texts. |
GET /v1/orgs/:orgId/marketing/lists/:listId | One list. |
PATCH /v1/orgs/:orgId/marketing/lists/:listId | Renames a list or changes its description, over version. |
DELETE /v1/orgs/:orgId/marketing/lists/:listId | Deletes a list no segment or unsent campaign uses (its members go in the background). |
GET /v1/orgs/:orgId/marketing/lists/:listId/members | A page of a list's members. |
POST /v1/orgs/:orgId/marketing/lists/:listId/members | Adds people by address (with merge fields for people not in Customers); admins may record the consent they gave elsewhere, with a note. |
POST /v1/orgs/:orgId/marketing/lists/:listId/members/remove | Removes people from a list by address. |
POST /v1/orgs/:orgId/marketing/lists/:listId/imports | Starts a CSV import: small files with the request (content), larger ones to the returned upload URL. |
GET /v1/orgs/:orgId/marketing/imports/:jobId | A list import's progress: rows read, added, skipped and why. |
GET /v1/orgs/:orgId/marketing/imports/:jobId/preview | The file's columns, a few rows and the suggested mapping. |
POST /v1/orgs/:orgId/marketing/imports/:jobId/start | Runs the import with a mapping (a target per column: email, phone, firstName, … or blank) and, for admins, the consent people gave. |
GET /v1/orgs/:orgId/marketing/segments | Segments, by name, with their last size estimate. |
POST /v1/orgs/:orgId/marketing/segments | A segment: OR-groups of Customers filters (relative dates $daysAgo:N), engagement and list conditions. |
POST /v1/orgs/:orgId/marketing/segments/preview | The first people a segment (saved or not) reaches, as the caller sees Customers: the builder's live preview. |
GET /v1/orgs/:orgId/marketing/segments/:segmentId | One segment with its groups and estimate. |
PUT /v1/orgs/:orgId/marketing/segments/:segmentId | Replaces a segment's name, description and groups over version (its estimate is cleared). |
DELETE /v1/orgs/:orgId/marketing/segments/:segmentId | Deletes a segment no unsent campaign or running journey uses. |
POST /v1/orgs/:orgId/marketing/segments/:segmentId/estimate | Counts the segment's people in the background (deduplicated by address); the result lands on the segment. |
GET /v1/orgs/:orgId/marketing/templates | Templates campaigns start from. |
POST /v1/orgs/:orgId/marketing/templates | A template: a block document campaigns can start from. |
GET /v1/orgs/:orgId/marketing/templates/:templateId | One template with its document. |
PATCH /v1/orgs/:orgId/marketing/templates/:templateId | Changes a template's name, description or document over version. |
DELETE /v1/orgs/:orgId/marketing/templates/:templateId | Deletes a template (campaigns made from it keep their copy). |
GET /v1/orgs/:orgId/marketing/blocks | Saved blocks in the content library. |
POST /v1/orgs/:orgId/marketing/blocks | Saves a block (with its columns, if any) to the content library. |
DELETE /v1/orgs/:orgId/marketing/blocks/:blockId | Deletes a saved block. |
GET /v1/orgs/:orgId/marketing/images | Images on the content library's CDN host. |
POST /v1/orgs/:orgId/marketing/images | An image upload: the URL the browser PUTs the file to; then finish. PNG, JPEG, GIF or WebP. |
POST /v1/orgs/:orgId/marketing/images/:imageId/finish | Finishes an upload: the file is checked and the image goes on the CDN host. |
DELETE /v1/orgs/:orgId/marketing/images/:imageId | Deletes an image (messages already sent keep showing it until it expires from caches). |
POST /v1/orgs/:orgId/marketing/preview | A message as one person would get it (a contact or lead the caller can read, else placeholder values), in a scheme and device. |
POST /v1/orgs/:orgId/marketing/test | A test to one to five members: "[Test]" in the subject, links work but don't count. |
GET /v1/orgs/:orgId/marketing/campaigns | Campaigns, newest first, with their numbers once sending started (status narrows them). |
POST /v1/orgs/:orgId/marketing/campaigns | A draft: a name, a topic, an audience (segments and lists to include and exclude) and content (a document, a template, or the starter). |
GET /v1/orgs/:orgId/marketing/campaigns/:campaignId | One campaign, and while it's a draft what stops it being sent (problems). |
PATCH /v1/orgs/:orgId/marketing/campaigns/:campaignId | Changes a draft over version; changing one waiting for approval, or approved, withdraws the request. |
DELETE /v1/orgs/:orgId/marketing/campaigns/:campaignId | Deletes a campaign that never sent. |
POST /v1/orgs/:orgId/marketing/campaigns/:campaignId/duplicate | A new draft with the same content and audience. |
POST /v1/orgs/:orgId/marketing/campaigns/:campaignId/request-approval | Asks the org's approvers (other than the caller) to approve the campaign as it stands. |
POST /v1/orgs/:orgId/marketing/campaigns/:campaignId/decide | An approver approves or declines (never their own request). |
POST /v1/orgs/:orgId/marketing/campaigns/:campaignId/schedule | Schedules for at (epoch ms; now when left out), optionally spread over a day to each person's usual hour. |
POST /v1/orgs/:orgId/marketing/campaigns/:campaignId/unschedule | Takes a scheduled campaign back (an approval stays). |
POST /v1/orgs/:orgId/marketing/campaigns/:campaignId/pause | Pauses a sending campaign within a page of recipients. |
POST /v1/orgs/:orgId/marketing/campaigns/:campaignId/resume | Resumes a paused campaign where it stopped. |
POST /v1/orgs/:orgId/marketing/campaigns/:campaignId/cancel | Cancels a scheduled, sending or paused campaign: nobody not yet sent it gets it. |
GET /v1/orgs/:orgId/marketing/campaigns/:campaignId/results | The campaign and its numbers (sent, delivered, opened, clicked, unsubscribed, bounced, conversions, revenue, …). |
GET /v1/orgs/:orgId/marketing/campaigns/:campaignId/recipients | The send's recipients and what happened to each, a page at a time. |
GET /v1/orgs/:orgId/marketing/campaigns/:campaignId/conversions | Won opportunities credited to the campaign, newest first. |
GET /v1/orgs/:orgId/marketing/journeys | Journeys, newest first, with how many people entered, are in them, completed and met the goal. |
POST /v1/orgs/:orgId/marketing/journeys | A draft journey (the definition is checked when it's published; problems lists what's missing). |
POST /v1/orgs/:orgId/marketing/journeys/sms-estimate | What a text step costs per message to each priced destination, for its text as written. |
GET /v1/orgs/:orgId/marketing/journeys/:journeyId | One journey with its draft, versions and approval, and what stops the draft going live (problems). |
PATCH /v1/orgs/:orgId/marketing/journeys/:journeyId | Changes the name, description or draft over version; the live version is untouched until the next publish. |
DELETE /v1/orgs/:orgId/marketing/journeys/:journeyId | Deletes a journey that never went live. |
POST /v1/orgs/:orgId/marketing/journeys/:journeyId/duplicate | A new draft journey from this one's draft. |
POST /v1/orgs/:orgId/marketing/journeys/:journeyId/request-approval | Asks the org's approvers (other than the caller) to approve the draft as it stands. |
POST /v1/orgs/:orgId/marketing/journeys/:journeyId/decide | An approver approves or declines the draft (never their own request). |
POST /v1/orgs/:orgId/marketing/journeys/:journeyId/publish | Publishes the draft as the next version and runs it; people already in it stay on theirs. |
POST /v1/orgs/:orgId/marketing/journeys/:journeyId/pause | Pauses a running journey: nobody enters and nobody moves on until it resumes. |
POST /v1/orgs/:orgId/marketing/journeys/:journeyId/resume | Resumes a paused journey: everyone carries on from where they held. |
POST /v1/orgs/:orgId/marketing/journeys/:journeyId/stop | Stops a journey for good: everyone in it leaves. |
POST /v1/orgs/:orgId/marketing/journeys/:journeyId/enter | Puts someone into a journey that takes entries by API: a Customers record, or an address with merge fields. |
GET /v1/orgs/:orgId/marketing/journeys/:journeyId/people | The journey's people and where each is, a page at a time. |
GET /v1/orgs/:orgId/marketing/journeys/:journeyId/people/:key | One person in the journey, by their email, mobile or rec:<record id>. |
GET /v1/orgs/:orgId/marketing/journeys/:journeyId/stats | Totals, each step's numbers (entered, completed, exited, goal reached) and each email and text step's send. |
GET /v1/orgs/:orgId/marketing/journeys/:journeyId/versions/:version | A published version as it was frozen. |
GET /v1/orgs/:orgId/marketing/forms | Forms with their submission and spam counts. |
POST /v1/orgs/:orgId/marketing/forms | A form: fields mapped to lead or contact fields, defaults, a consent box (topics and wording) and what happens after. |
GET /v1/orgs/:orgId/marketing/forms/:formId | One form, with its consent wordings and the HTML that embeds it. |
PUT /v1/orgs/:orgId/marketing/forms/:formId | Replaces a form over version; a new consent wording becomes a new version and the old ones are kept. |
DELETE /v1/orgs/:orgId/marketing/forms/:formId | Deletes a form no running journey enters people from. |
GET /v1/orgs/:orgId/marketing/forms/:formId/submissions | The form's submissions, newest first. |
GET /v1/orgs/:orgId/marketing/pages | Landing pages with their views. |
POST /v1/orgs/:orgId/marketing/pages | A landing page: a block document with forms, at a slug in the org. |
GET /v1/orgs/:orgId/marketing/pages/:pageId | One landing page (its draft and what was published) and its public address. |
PATCH /v1/orgs/:orgId/marketing/pages/:pageId | Changes the draft, name or address over version. |
POST /v1/orgs/:orgId/marketing/pages/:pageId/publish | Puts the draft live at /p/<org>/<slug> on the Marketing app. |
POST /v1/orgs/:orgId/marketing/pages/:pageId/unpublish | Takes a page down until it is published again. |
DELETE /v1/orgs/:orgId/marketing/pages/:pageId | Deletes a landing page and frees its address. |