Skip to main content

External campaign automation overview

External campaign automation lets you compose and launch external campaigns without going through the Accelerator UI — today by script or pipeline, calling the underlying REST API directly, and soon through an AI agent like Claude driving the same workflow on your behalf via MCP. Either way, a client drives the full lifecycle from campaign creation to a live audience send, and the campaigns it creates appear in Accelerator like any other.

Under the hood, this is powered by a REST API served at https://{host}/messagegears-api/v1, authenticated with the same API key used across MessageGears' refreshed Accelerator APIs, sent in the apiKey header. For more information about getting a key and the entities you need before your first call, see External campaign automation prerequisites.

note

This article is accurate as of Accelerator 26.3.2. Verify field types, enums, and error codes against your environment's endpoint reference before building a client.

  • SQL audience sources only - The audience you attach to a campaign must be a SQL-based audience source. Blueprint audiences are modeled in the schema for forward compatibility but are not attachable in 26.3.2 — attempting to attach one returns 409 AUDIENCE_BLUEPRINT_CONFLICT.
  • No audience preview - There is no endpoint to sample rows from a source before you attach it and launch.

The endpoint types​

Under the hood, every endpoint falls into one of six types, ordered to match how you build a campaign:

GroupWhat it's for
DiscoveryRead-only lookups to find the IDs you reference everywhere else — audience sources, destinations, brands, accounts, timezones.
Campaign coreCreate, list, and read the campaign itself, independent of any facet.
Attach and configureAttach or update each facet a campaign needs. Order-independent except where a facet's own rules say otherwise.
Verify configurationRead back what's attached to a campaign, one facet at a time.
Launch and monitorTrigger a send and monitor the resulting job.
Detach and deleteDetach a facet, or delete the campaign outright. Mostly unguarded — the exceptions are called out per operation.

What makes this unique​

Several design decisions distinguish this API from a conventional integration surface — decisions that matter whether the caller is your own script or an AI agent acting with less direct human oversight:

  • Flat pagination envelopes - List endpoints return a consistent structure: items, page (zero-based), size, totalElements, and totalPages. No nested or embedded wrappers.
  • Stable error codes - Every error response carries a code field drawn from a stable enum, plus a retryable flag. Branch your error handling on code and retryable — the message field is for human readers and may change. For more information, see How external campaign automation works.
  • Guarded commit points - The calls that commit to a real send — deleting a campaign, arming a schedule, and launching — require an explicit confirm: true in the request body. Without it, the call returns 409 CONFIRMATION_REQUIRED and mutates nothing. This stops an automation from committing on a hallucinated or unverified intent.

Automation vs. the Accelerator UI​

External campaign automation and the Accelerator UI operate on the same underlying campaigns and destinations. Choose the surface that fits your situation:

If you…Use
Want to build automated pipelines that create and launch campaigns in response to events or on a scheduleExternal campaign automation
Are integrating MessageGears into an AI agent or LLM-driven workflowExternal campaign automation
Are setting up a destination for the first time or need to authorize a vendor connectionAccelerator UI
Prefer a guided, form-based workflow for a one-off campaignAccelerator UI

Destinations configured for your UI are usable by automation, and campaigns you create through automation appear in Accelerator. For more information about setting up destinations in the UI, see External destinations.

Next steps​