# Campaign Refinery Documentation

> Campaign Refinery API gives developers access to a robust, modern marketing automation tool to manage contacts and kick-off marketing sequences.

## Guides
- [REST API Migration Guide](https://developers.campaignrefinery.com/docs/rest-api-migration-guide.md)
- [Getting Started](https://developers.campaignrefinery.com/docs/getting-started.md)

## API Reference
- [Get an API Key](https://developers.campaignrefinery.com/reference/get-an-api-key.md)
- [Use Your API Key](https://developers.campaignrefinery.com/reference/test-authentication.md): All Campaign Refinery API endpoints use bearer authentication. Send your key in the HTTP `Authorization` header:  ```http Authorization: Bearer YOUR_API_KEY ```  You can verify a key works in seconds with the Try It panel below. A valid key returns `{"status": true, "message": "OK", "account": "Account Name (account_email)"}`. The `account` field identifies the connected account, which integrations such as Zapier use to label the connection.  > **Keep your key secret.** Do not put API keys in browser JavaScript, mobile apps, public repositories, screenshots, support tickets, or query strings. Store them in a server environment variable or a secrets manager. If you rotate a key, update the service that uses it before revoking the old one.  If a request returns `401`, the most common causes are: missing `Bearer ` prefix, a stray space, the wrong account's key, or a revoked key. Your key is managed under your account's [API Keys](https://app.campaignrefinery.com/settings/api-keys) page.
- [Get Contacts](https://developers.campaignrefinery.com/reference/get-contacts.md): Returns a paginated list of contacts in the authenticated account. Each row is identified by `contact_uuid`. Optional `with_attributes=true` adds a nested `custom_attributes` map per contact (default omits, opt-in). Pagination uses the standard paginated response envelope inside `data` (`{current_page, data: [...], total, per_page, last_page, ...}`).
- [Get Contact](https://developers.campaignrefinery.com/reference/get-contact.md): Returns a single contact in the authenticated account, identified by `contact_uuid` OR `contact_email` (at least one required; supplying both narrows the match). Optional `with_attributes=true` adds a nested `custom_attributes: {key: value}` map to the response; by default custom attributes are omitted.
- [Update Contact](https://developers.campaignrefinery.com/reference/update-contact.md): Updates an existing contact identified by `id` (contact UUID) in the authenticated account. Pass `domain` to route the update to a sub-account in the same billing group. All field updates are partial -- only fields supplied in the body are written. `name` is a fallback that is split into `first_name` / `last_name` if those are not provided directly.
- [Add Goal to Contact](https://developers.campaignrefinery.com/reference/add-goal.md): Marks a goal as completed for a contact in the authenticated account. Both `id` (contact UUID) and `goal_id` (goal UUID) must belong to the authenticated account; if either does not exist, the endpoint returns 404.
- [Add Form to Contact](https://developers.campaignrefinery.com/reference/add-form.md): Attaches a form to a contact in the authenticated account. Both `id` (contact UUID) and `form_id` (form UUID) must belong to the authenticated account; if either does not exist, the endpoint returns 404.
- [Subscribe Contact](https://developers.campaignrefinery.com/reference/subscribe-contact.md): Creates a new contact (or updates an existing one keyed by email) for the authenticated account, applies tag/sequence/form/goal mappings, and resolves any provided custom attributes. Pass `create_only: true` to fail with HTTP 400 instead of upserting when a contact with the same email already exists -- this replaces the legacy `/rest/contacts/create-contact` endpoint, which was an alias of `subscribe` with the flag pre-set. Pass `domain` to route the subscription to a sub-account in the same billing group.
- [Get Contact Tags](https://developers.campaignrefinery.com/reference/get-contact-tags.md): Returns the tags currently attached to a contact in the authenticated account. Contact is identified by `id` (contact UUID) OR `email`; at least one is required. Each tag includes `tag_uuid`, `tag_name`, and `tag_added_dts`. Both GET and POST are accepted.
- [Add Tags to Contact](https://developers.campaignrefinery.com/reference/add-tags.md): Adds one or more existing tags to a contact by UUID. Either tag_id (single tag) or tag_ids (comma-separated list) must be provided. Tag UUIDs that do not resolve to a tag in the authenticated account are reported in the 'skipped' response array; resolved tags are returned by name in 'added' (asymmetric -- 'added' contains names, 'skipped' contains UUIDs). The legacy singular path /contacts/add_tag also accepts the same payload as an undocumented alias.
- [Remove Tags from Contact](https://developers.campaignrefinery.com/reference/delete-tags.md): Removes one or more tags from a contact by UUID. Either tag_id (single tag) or tag_ids (comma-separated list) must be provided. 'removed' lists names of tags actually detached. 'skipped' lists UUIDs that either didn't resolve to a tag in this account or resolved but were not currently attached to the contact -- both cases mean the tag was not removed (because it wasn't there to begin with). The legacy singular path /contacts/delete_tag also accepts the same payload as an undocumented alias.
- [Unsubscribe Contact](https://developers.campaignrefinery.com/reference/unsubscribe-contact.md): Unsubscribes a contact identified by `email` or `id` (contact UUID). At least one is required; `id` takes precedence when both are supplied. Unsubscribing an already-unsubscribed contact succeeds. Pass `domain` to target a sub-account in the same billing group.
- [Get Tag](https://developers.campaignrefinery.com/reference/get-tag.md): Look up a single tag by either its UUID or its name. Exactly one of `tag_uuid` or `tag_name` is required; supplying neither returns 422 with errors on both fields. Both GET and POST are accepted.
- [List Tags](https://developers.campaignrefinery.com/reference/list-tags.md): Returns a paginated list of tags for the authenticated account, optionally filtered by a name search. Both GET and POST are accepted. Response payload uses the standard paginated envelope. Results are ordered newest-first by default; pass `order_by=name` for alphabetical order.
- [Create Tag](https://developers.campaignrefinery.com/reference/create-tag.md): Creates a new tag for the authenticated account, optionally nested under an existing parent tag. The submitted `tag_name` is normalized server-side before storage: each `~` is replaced with a space, runs of one or more commas are replaced with a single hyphen, Unicode control and format characters (newline, NUL, BOM, etc.) are stripped, and surrounding whitespace is trimmed. This keeps the stored name safe across the system's `~`- and `,`-delimited tag pipelines (click-tracked URLs, comma-separated tag-list inputs); a caller who submits `foo,bar` will see `foo-bar` in the response. A `tag_name` that is empty after this normalization (only whitespace or control characters) is rejected with 422.
- [Update Tag](https://developers.campaignrefinery.com/reference/update-tag.md): Updates the name and/or parent of an existing tag in the authenticated account. The tag is identified by `tag_uuid` in the URL path. The submitted `tag_name` is normalized server-side before storage with the same rules as `/tags/create_tag` (`~` -> space, runs of `,` -> `-`, Unicode control/format characters stripped, whitespace trimmed); a `tag_name` empty after normalization is rejected with 422. Setting a tag as its own parent is rejected with 422. If another tag in the account already has the submitted name, 409 is returned with the conflicting tag's UUID and name in `data` so callers can recover without a separate lookup.
- [Delete Tag](https://developers.campaignrefinery.com/reference/delete-tag.md): Schedules a tag for asynchronous deletion. The tag UUID is part of the URL path; no request body is required. Returns 200 immediately once deletion has been queued. Related contact-tag mappings, automation triggers, email-tag actions, event-tag relations, and audience filters are removed asynchronously and are not returned to the caller.
- [Get Goal](https://developers.campaignrefinery.com/reference/get-goal.md): Looks up a single goal by either its UUID or its name. Exactly one of `goal_uuid` or `goal_name` is required; supplying neither returns 422 with errors on both fields. Both GET and POST are accepted.
- [List Goals](https://developers.campaignrefinery.com/reference/list-goals.md): Returns a paginated list of goals for the authenticated account, optionally filtered by campaign. Both GET and POST are accepted. Response payload uses the standard paginated envelope.
- [Create Goal](https://developers.campaignrefinery.com/reference/create-goal.md): Creates a new goal for the authenticated account, optionally linked to a campaign and pre-populated with tag mappings.
- [Update Goal](https://developers.campaignrefinery.com/reference/update-goal.md): Updates an existing goal (name, match type, tag mappings). The goal is identified by `goal_uuid` and must belong to the authenticated account. Tag mappings are only rewritten when `tag_ids` is sent in the body: omit the field to leave existing mappings untouched, send an empty array to clear them.
- [Get Form](https://developers.campaignrefinery.com/reference/get-form.md): Look up a single form by either its UUID or its name. At least one of `form_uuid` or `form_name` is required; supplying neither returns 422. The response includes the form's full configuration plus a flat list of attached field mappings (`form_field_maps`), where each entry merges the form-field row with its custom attribute and that attribute's group.
- [Get Forms](https://developers.campaignrefinery.com/reference/get-forms.md): Returns a paginated list of forms belonging to the authenticated account. Supports search by name (substring `LIKE`), filtering by `form_uuid` or `campaign_uuid`, and ordering. Each returned item contains `form_uuid`, `form_name`, `form_created_dts`, and `campaign_uuid`. Pagination is `page` / `per_page` and the response shape is the standard paginated envelope (`current_page`, `data`, `total`, `per_page`, `last_page`, etc.).
- [Create Form](https://developers.campaignrefinery.com/reference/create-form.md): Creates a new form for the authenticated account. `form_name` must be unique within the account; duplicate names return 422. Optional `campaign_uuid` attaches the form to a campaign; optional `form_code_*` fields configure the embeddable form widget (success URL, recaptcha keys, etc.). The response includes the new form's UUID and display fields.
- [Update Form](https://developers.campaignrefinery.com/reference/update-form.md): Updates name, campaign attachment, and/or `form_code_*` configuration on an existing form. The form is identified by `form_uuid` in the URL path. All body fields are optional -- only fields that are present are written. `form_name` must remain unique within the account (the duplicate check ignores the form being updated).
- [Delete Form](https://developers.campaignrefinery.com/reference/delete-form.md): Deletes a form by UUID. The form UUID is part of the URL path (legacy callers passed it as `id` in the body; the new shape is path-based). The authenticated API key selects the account.
- [Get Attribute](https://developers.campaignrefinery.com/reference/get-attribute.md): Returns a single custom attribute belonging to the authenticated account, joined with its group. Lookup is by either `custom_attr_uuid` (UUID) or `custom_attr_key`. Both are accepted in the body; supplying both narrows the match. Returns 422 if neither field is supplied, 404 if no attribute matches in the account.
- [Get Attributes](https://developers.campaignrefinery.com/reference/get-attributes.md): Returns custom attributes belonging to the authenticated account, joined with their group. Optional filters: `custom_attr_group_uuid` (account-scoped UUID, returns 422 if unknown), `custom_attr_key` (attribute key). Optional `order_by` map of `column => direction` for sorting; valid columns are `custom_attr_display_order`, `custom_attr_name`, `custom_attr_key`, `custom_attr_type`, `custom_attr_group_name`. Default order: `custom_attr_display_order ASC, custom_attr_name ASC`.
- [Get Attribute Groups](https://developers.campaignrefinery.com/reference/get-attribute-groups.md): Returns custom attribute groups belonging to the authenticated account, ordered alphabetically by `custom_attr_group_name`.
- [Create Attribute](https://developers.campaignrefinery.com/reference/create-attribute.md): Creates a custom attribute within an existing group in the authenticated account. `name` must be unique within the (account, group) tuple -- duplicates return 422. `type` is fixed at creation time and cannot be changed via update; allowed values are the actual storage column types (`varchar`, `mediumtext`, `int`, `decimal`, `datetime`). The response includes the generated `custom_attr_key`; use that key for contact subscribe and form-field mapping.
- [Update Attribute](https://developers.campaignrefinery.com/reference/update-attribute.md): Updates the display name of an existing custom attribute. The attribute is identified by its UUID in the URL path. Only `name` can be changed -- `type` is fixed at creation time. The returned `custom_attr_key` can change when the name changes; use the key from the update response for future contact-attribute writes.
- [Create Custom Attribute Group](https://developers.campaignrefinery.com/reference/create-group.md): Creates a new custom attribute group for the authenticated account. The legacy field name `name` was renamed to `group_name`. The client-facing identifier in the response is `custom_attr_group_uuid`.
- [Get Broadcasts](https://developers.campaignrefinery.com/reference/get-broadcasts-with-stats.md): Returns a paginated list of broadcasts for the authenticated account. Pass with_stats=true to include delivery and engagement stats in each broadcast item. The authenticated API key selects the account. Both GET and POST are accepted.
- [List broadcast messages](https://developers.campaignrefinery.com/reference/get-broadcast-messages.md): Returns a paginated list of broadcast messages (the working copies of messages attached to specific broadcasts), scoped to the authenticated account. Broadcast messages cannot be edited in place — to make a variation, clone the message and edit the clone.
- [List message templates](https://developers.campaignrefinery.com/reference/get-templates.md): Returns a paginated list of non-deleted message templates for the authenticated account. The authenticated API key selects the account. Both GET and POST are accepted.
- [Get message template](https://developers.campaignrefinery.com/reference/get-template.md): Returns a single non-deleted message template by UUID, scoped to the authenticated account. The body comes back as three fields: `html_content` (the visual-editor HTML), `raw_html_content` (custom raw HTML supplied by the user), and `use_raw_html_content` (when true, `raw_html_content` is the body that sends; otherwise `html_content` sends -- and if `use_raw_html_content` is true but `raw_html_content` is empty, the system falls back to `html_content`).
- [Update message template](https://developers.campaignrefinery.com/reference/update-template.md): Applies a partial update to an existing template; all fields are optional. References the sending domain and footer by UUID. When `use_raw_html_content` changes, the inactive body field is cleared automatically. If `from_email` or `reply_to_email` are supplied, their domain must match the sending domain of the new or existing EDS. Returns the full updated template.
- [Cancel a broadcast](https://developers.campaignrefinery.com/reference/cancel-broadcast.md): Cancels a scheduled or in-progress broadcast. The authenticated API key selects the account.
- [Create a broadcast](https://developers.campaignrefinery.com/reference/create-broadcast.md): Creates a broadcast in a single call. Provide the message inline (`message`) or reference an existing template (`template_uuid`) -- exactly one of the two. Provide the audience as a segment (`audience_uuid`) or a group (`audience_group_uuid`) -- exactly one of the two. Optionally schedule it with `schedule`, or send as soon as possible with `send_asap`.
- [Create message template](https://developers.campaignrefinery.com/reference/create-template.md): Creates a new message template for the authenticated account. References the sending domain and footer by UUID. Supply either `html_content` (visual-editor HTML) or `raw_html_content` (custom raw HTML with `use_raw_html_content` set to true). If `from_email` or `reply_to_email` are supplied, their domain must match the sending domain of the referenced EDS.
- [Delete a broadcast](https://developers.campaignrefinery.com/reference/delete-broadcast.md): Soft-deletes a broadcast. The authenticated API key selects the account.
- [Delete message template](https://developers.campaignrefinery.com/reference/delete-template.md): Soft-deletes a message template by UUID, scoped to the authenticated account.
- [Get broadcast message](https://developers.campaignrefinery.com/reference/get-broadcast-message.md): Returns a single broadcast message by UUID, scoped to the authenticated account. The body comes back as three fields: `html_content` (the visual-editor HTML), `raw_html_content` (custom raw HTML supplied by the user), and `use_raw_html_content` (when true, `raw_html_content` is the body that sends; otherwise `html_content` sends -- and if `use_raw_html_content` is true but `raw_html_content` is empty, the system falls back to `html_content`).
- [Get a broadcast](https://developers.campaignrefinery.com/reference/get-broadcast.md): Returns a single broadcast by UUID, scoped to the authenticated account, including message, audience, and attached suppression lists. Both GET and POST are accepted.
- [Schedule a broadcast](https://developers.campaignrefinery.com/reference/schedule-broadcast.md): Schedules a broadcast for a future time (`scheduled_dts`) or queues it to send immediately (`send_asap`: true). When `send_asap` is not true, `scheduled_dts` is required.
- [Set broadcast audience](https://developers.campaignrefinery.com/reference/set-broadcast-audience.md): Sets the audience of an existing broadcast to a segment (`audience_uuid`) or a group (`audience_group_uuid`). Exactly one of the two must be supplied.
- [Update broadcast message content](https://developers.campaignrefinery.com/reference/update-broadcast-message.md): Replaces the message content of an existing broadcast. References the sending domain and footer by UUID. Either `html_content` or `raw_html_content` must be supplied. If `from_email` or `reply_to_email` are supplied, their domain must match the sending domain of the referenced EDS.
- [Update a broadcast](https://developers.campaignrefinery.com/reference/update-broadcast.md): Renames an existing broadcast and optionally replaces its suppression lists and tag actions. The authenticated API key selects the account. `suppression_uuids` and `actions` are full replacements: if you send a list, that IS the list -- the broadcast ends up with exactly what the array contains, and anything previously attached but not re-sent is removed. Send `[]` to clear the set. Omit the field entirely to leave the current set untouched.
- [Get Top Ranked Contacts](https://developers.campaignrefinery.com/reference/get-ranked-balance.md): Returns top contacts ranked by `contact_points_balance` for the authenticated account, optionally filtered by tag UUIDs. Each result is identified by `contact_uuid`. The list is bounded by `limit` (default 25, max 100). **Tag filtering accepts UUIDs only** -- the legacy CI contract that filtered by tag NAMES (`with_tags=name1,name2`) is no longer supported on the new REST surface; unknown tag UUIDs return 422 with a canonical envelope. Both `with_tag_uuids` and `without_tag_uuids` accept either a comma-separated string OR a JSON array.
- [Get Daily Points Activity](https://developers.campaignrefinery.com/reference/get-daily-points.md): Returns daily points in/out for all contacts who earned or redeemed points within the target UTC date. `cumulative_balance` is the contact's closing balance at end-of-day (23:59:59 UTC) on the target date. Each row is identified by `contact_uuid`. Invalid `date` values are rejected with 422.
- [Get Overall Points Balance Report (CSV)](https://developers.campaignrefinery.com/reference/get-points-balance.md): Returns the overall points-balance report for all account contacts as a CSV string wrapped in the canonical envelope. The CSV body has columns `id,email,points balance` -- the `id` column carries each contact's UUID. The report is generated at most once per 24 hours per account and served from cache on subsequent requests until the next 24h window. While generation is in progress, the endpoint returns HTTP 202 with a canonical envelope (`success: true`, `message: "Report still processing."`); subsequent requests during the same generation cycle continue to return 202 until the file is ready. On infrastructure error the endpoint returns HTTP 503 with a canonical error envelope. The `linebreak` parameter controls the linebreak character WITHIN the CSV string (it does NOT affect the JSON envelope itself).
- [Send Single Email](https://developers.campaignrefinery.com/reference/send-single-email.md): Send a single email to a contact using raw HTML content. Supports two recipient modes: by email address or by contact UUID. In both modes the recipient must exist as a non-deleted contact in the account; unknown or deleted recipients return 404 "Contact not found". Contacts that have opted out are never sent to; both modes return 422 "Contact is opted out".
- [Send Bulk Emails](https://developers.campaignrefinery.com/reference/send-bulk-email.md): Send bulk emails to multiple contacts using raw HTML content. Supports two recipient modes: by email addresses or by contact UUIDs.
- [Get Cleaning Status](https://developers.campaignrefinery.com/reference/get-cleaning-status.md): Returns the status of a bulk cleaning job. `status` is `processing` until the job finishes, then `completed` with `completed_at` set. The same identifier is returned in the response body as `job_uuid`.
- [Clean Bulk Emails](https://developers.campaignrefinery.com/reference/clean-bulk-email.md): Submit a batch of email addresses for cleaning. Provide either a CSV file upload (`multipart/form-data`) or a JSON body with an `emails` array (max 500). Cleaning runs asynchronously; the response returns a `job_uuid` to poll with Get Cleaning Status or to download once complete. By default the account owner is emailed when the job finishes; supply `notify_email` to send elsewhere, or an HTTPS `callback_url` to receive a webhook instead of an email.
- [Download Cleaning File](https://developers.campaignrefinery.com/reference/download-cleaning-file.md): Downloads the cleaned results CSV for a completed bulk cleaning job, identified by `job_uuid`.
- [Get Cleaning Files](https://developers.campaignrefinery.com/reference/get-cleaning-files.md): Returns a paginated list of bulk cleaning jobs for the authenticated account. Each row is identified by `job_uuid`.
- [Get Cleaning Singles](https://developers.campaignrefinery.com/reference/get-cleaning-singles.md): Returns a paginated history of individually cleaned email addresses for the authenticated account.
- [Add Webhook](https://developers.campaignrefinery.com/reference/webhooks-add.md): Add webhook(s) to your ESP (Email Service Provider) to receive event notifications. If event_type is provided, adds a webhook for that specific event only. Otherwise, adds webhooks for every event supported by the domain's provider. The domain must belong to your account or, for billing group owners, to a sub-account in your billing group; unknown domains return 404.
- [Remove Webhook](https://developers.campaignrefinery.com/reference/webhooks-remove.md): Remove webhook(s) from your ESP. If event_type is provided, removes the webhook for that specific event only. If target_url is provided, removes that URL from all event types. Otherwise, removes all webhooks except the protected Campaign Refinery system webhook. The domain must belong to your account or, for billing group owners, to a sub-account in your billing group; unknown domains return 404.
- [List Webhooks](https://developers.campaignrefinery.com/reference/webhooks-list.md): List all configured webhooks for a domain, including the supported event types. The domain must belong to your account or, for billing group owners, to a sub-account in your billing group; unknown domains return 404.
- [Verify ESP Credentials](https://developers.campaignrefinery.com/reference/webhooks-verify.md): Verify that the ESP credentials of the account owning the given domain are valid and the API connection is working properly. The domain must belong to your account or, for billing group owners, to a sub-account in your billing group; unknown domains return 404.
- [Clone campaign](https://developers.campaignrefinery.com/reference/clone-campaign.md): Duplicates a campaign -- including its sequences and events -- into the authenticated account and returns the new copy in the `get_campaign` shape (HTTP `201`). The source may be either a campaign owned by the account or a campaign published to the shared library; the clone's name is prefixed with `Clone of`. Every duplicated record receives fresh UUIDs.
- [Clone sequence](https://developers.campaignrefinery.com/reference/clone-sequence.md): Creates a copy of a sequence (including its events) within the same campaign and returns the new sequence (same shape as `get_sequence`, HTTP `201`). The clone gets its own `sequence_uuid` and per-event `event_uuid` values.
- [Create campaign](https://developers.campaignrefinery.com/reference/create-campaign.md): Creates a campaign for the authenticated account and returns it in the same UUID-only shape as `get_campaign` (HTTP `201`). `campaign_type` must be one of the supported type keys (see the enum). `eds_uuid` (the sending domain / email delivery system) and `footer_uuid` are required and must reference resources owned by the account -- they become the campaign's defaults and propagate to emails added to its sequences. List the available delivery systems via `GET /rest/eds/get_eds` and footers via `GET /rest/footers/get_footers`. After creating the campaign, add sequences to it with `create_sequence`.
- [Create sequence](https://developers.campaignrefinery.com/reference/create-sequence.md): Adds a sequence to an existing campaign and returns it in the same UUID-only shape as `get_sequence` (HTTP `201`). New sequences start with no events -- add them with `create_event` (see the Sequences endpoints). The campaign must belong to the authenticated account.
- [Delete campaign](https://developers.campaignrefinery.com/reference/delete-campaign.md): Soft-deletes a campaign owned by the authenticated account and cascades the soft-delete to its sequences, events, and automation rules. Linked forms, goals, merge tags, and campaign links are unlinked, and library/sequence-map rows are removed. Returns HTTP `200` with an empty `data`. The operation is effectively idempotent from the caller's view: a campaign that is already deleted (or never existed) returns `404`.
- [Delete sequence](https://developers.campaignrefinery.com/reference/delete-sequence.md): Soft-deletes a sequence owned by the account. A sequence that is wired in as a cold-engagement re-engagement sequence cannot be deleted until it is removed from cold-engagement settings (`409`).
- [Get campaign suppression data](https://developers.campaignrefinery.com/reference/get-campaign-suppression-data.md): Returns the suppression-list picker for a campaign: `suppression_lists` is every suppression list in the account (each with its UUID and name), and `selected_suppression_list_uuids` is the subset currently applied to the campaign. Use this to render a selection UI, then persist changes with `save_campaign_suppression_lists`. This route accepts either `GET` (with `campaign_uuid` as a query-string parameter) or `POST` (with the JSON body shown here).
- [Get campaign](https://developers.campaignrefinery.com/reference/get-campaign.md): Returns a single campaign by `campaign_uuid`, scoped to the authenticated account. Alongside the campaign metadata the response carries `eds_uuid` and `footer_uuid` -- the email delivery system (sending domain) and footer currently set as the campaign's defaults; these propagate to emails created inside the campaign's sequences. `num_sequences` is the count of non-deleted sequences. The returned `eds_uuid`/`footer_uuid` are the values to echo back (or change) on an `update_campaign` call. This route accepts either `GET` (with `campaign_uuid` as a query-string parameter) or `POST` (with the JSON body shown here).
- [List campaigns](https://developers.campaignrefinery.com/reference/get-campaigns.md): Returns a paginated list of campaigns scoped to the authenticated account, newest first by default. Each item carries `eds_uuid`/`footer_uuid` (the campaign's default sending domain and footer) and `num_sequences` (count of non-deleted sequences). This is the entry point of the campaign flow: list campaigns here, then fetch one with `get_campaign`, drill into a sequence with `get_sequence`, or create a new campaign with `create_campaign`. Pagination is offset-based via `limit`/`offset`; `total` is the full count before paging.
- [Get campaign sequence](https://developers.campaignrefinery.com/reference/get-sequence.md): Returns a campaign sequence by `sequence_uuid`, scoped to the authenticated account. The response contains the sequence metadata and its `events` array, ordered by `event_order` (deleted events excluded). Scheduling lives only on `delay_timer` events, which carry `delay` ({days, hours, minutes}), `run_on_days` (allowed weekdays `mon`..`sun`; an empty array means any day), and `run_at_time` (`HH:MM`, or null to fire as soon as the wait elapses). Note: `delay.days` counts to calendar-midnight boundaries in the account timezone, so 1 day means 'until the next midnight', not a fixed 24 hours. Every non-delay event type runs immediately after the preceding event. Email events (`send_email`, `send_notification`) include an `email` object whose body is `html_content` / `raw_html_content` / `use_raw_html_content` (same semantics as the broadcast endpoints).
- [List sequences in a campaign](https://developers.campaignrefinery.com/reference/get-campaign-sequences.md): Returns a paginated list of the sequences belonging to a campaign (identified by `campaign_uuid`), scoped to the authenticated account, newest first. Each item carries `num_events` (count of non-deleted events) but not the events themselves -- fetch a single sequence with its events via `get_sequence`. Pagination is offset-based via `limit`/`offset`; `total` is the full count before paging.
- [Save campaign suppression lists](https://developers.campaignrefinery.com/reference/save-campaign-suppression-lists.md): Replaces the campaign's suppression-list assignments with the supplied set (a full replace, not an incremental add). `suppression_list_uuids` must be present; send an empty array to clear all assignments. Only UUIDs of suppression lists owned by the account are applied -- unknown or foreign UUIDs are silently ignored. Returns HTTP `200` with an empty `data`. Read the current assignments and the available lists first with `get_campaign_suppression_data`.
- [Set sequence goal](https://developers.campaignrefinery.com/reference/set-sequence-goal.md): Sets or clears the goal that halts a sequence. Provide a `goal_uuid` to assign that goal as the sequence's halt condition, or send `null` to clear it. `goal_uuid` must be present in the body either way. Returns the full sequence (same shape as `get_sequence`), reflecting the resulting `goal_uuid`.
- [Update campaign](https://developers.campaignrefinery.com/reference/update-campaign.md): Updates an existing campaign (identified by `campaign_uuid`) and returns it in the `get_campaign` shape. All fields are required -- send the full desired state, not a partial patch. Changing `eds_uuid` or `footer_uuid` re-points the campaign's defaults and propagates them to the emails in its sequences; both must reference resources owned by the account. The library flag (`campaign_in_library`) is preserved and is not editable through this endpoint.
- [Update sequence](https://developers.campaignrefinery.com/reference/update-sequence.md): Updates a sequence and returns the full sequence (same shape as `get_sequence`). `sequence_name` is required; `sequence_is_active`, `run_multiple`, and `run_multiple_reset` are optional toggles (`0`/`1`). Toggling `sequence_is_active` from `0` to `1` reschedules the sequence's pending events; if that reschedule cannot complete, the whole update is rolled back and a `503` is returned -- retry after a few seconds.
- [Create event](https://developers.campaignrefinery.com/reference/create-event.md): Adds an event to a sequence and returns it (HTTP `201`). The accepted body depends on `event_type`: supply only the parameters that belong to that type (extras are rejected with `422`, and a type's required parameters must be present). Call `sequence_events` for the per-type parameter list. Note: `footer_id` and `suppression_list_id` are UUIDs despite their names. The new event is appended after the sequence's existing events.
- [Delete event](https://developers.campaignrefinery.com/reference/delete-event.md): Soft-deletes an event owned by the account and returns a confirmation.
- [Get event](https://developers.campaignrefinery.com/reference/get-event.md): Retrieves a single event by `event_uuid`. The response is UUID-only and includes the event's type-specific configuration: `email` for Send Email / Send Notification, `event_http` for HTTP POST, `tags` (tag UUIDs) for Add/Remove Tags, `delay`/`run_on_days`/`run_at_time` for Delay Timer, `advance_campaign_link` (`cls_uuid` + `keep_after_sequence_ends`) for Advance Campaign Link, and `event_parameters` for Clone Field Data (`field_from`/`field_to`) and Suppress Email (`suppression_list_id`, returned as a UUID). `event_parameters` is an empty array for event types that carry no extra parameters.
- [List available event types](https://developers.campaignrefinery.com/reference/list-sequence-events.md): Returns the catalog of event types that can be added to a sequence, each with its human label and its parameter specification (`name`, `type`, `required`). Use this to drive `create_event`: the `parameters` list is the authoritative source for which fields each `event_type` accepts. Two parameter names end in `_id` but expect UUIDs: `footer_id` (Send Email / Send Notification) and `suppression_list_id` (Suppress Email).
- [Update event](https://developers.campaignrefinery.com/reference/update-event.md): Replaces an event's configuration in place and returns it. The event is identified by `event_uuid`; its `event_type` is fixed at creation (you cannot change it here). Supply only the parameters that belong to that type -- extras are rejected with `422`. Event types that cannot be reconfigured via the API return `422`.