External campaign automation prerequisites
Before you automate external campaigns, you need an API key and the entity IDs for the audience source and destination you intend to use. This article covers both, plus how to authenticate your requests.
For more information, see External campaign automation overview.
Get an API key​
External campaign automation requires a key created by a user with the External campaign author role, or broader. For the general key-creation steps, see Automation overview: Prerequisites and API key management. When you set the key's Brand association, make sure it covers every Brand whose campaigns, audiences, or destinations you intend to automate — see How Brand scope affects key access for what happens if it doesn't.
How Brand scope affects key access​
Brand scope only applies where the brands feature is enabled for your environment. If it isn't, skip this section — a key can reach every account, audience source, destination, and campaign the calling user's role permits, with no Brand-based restriction.
Where brands are enabled, a key's Brand scope determines which accounts, audience sources, destinations, and campaigns it can reach. A call for an entity outside the key's Brand scope fails the same way a nonexistent entity does — some endpoints return a plain 404 rather than 403 for an out-of-scope ID, so the two are hard to tell apart from the response alone.
A key's assigned Brands cannot be changed after creation. To change what a key can reach, create a new key with the correct scope and retire the old one.
Authenticate your requests​
Send the key in the apiKey header on every request:
GET /messagegears-api/v1/external
apiKey: your-api-key
| Status | Code | Cause |
|---|---|---|
401 | UNAUTHENTICATED | The apiKey header is missing or the key is invalid. |
403 | FORBIDDEN | The key's role or brand scope does not permit this operation. |
429 | RATE_LIMITED | The per-key rate limit is exceeded. Honor the Retry-After response header, given in seconds, before retrying. |
Entities you need before you start​
External campaign automation associates by entity ID — it does not create the underlying audience source or destination. These must already exist before you can attach them to a campaign:
- An audience source - A SQL-based audience source that produces the recipient list for the campaign. Discover available sources with
GET /messagegears-api/v1/audience-source. - At least one destination - A configured destination such as a Meta Custom Audience or an SFTP connection. Discover available destinations with
GET /messagegears-api/v1/destination.
You do not need an account or brand ID ready in advance. A campaign is auto-assigned the platform's default account at creation, and — where the brands feature is enabled — auto-seeded from the brand association of the user who owns the API key. Both are reassignable afterward if you need something other than the default.
Discover the IDs​
Before creating a campaign, look up the IDs for the entities you will attach:
| What you need | Endpoint |
|---|---|
| Audience source ID and available fields | GET /audience-source, then GET /audience-source/{id} |
| Data variables on that source | GET /audience-source/{id}/local-data-variables and .../global-data-variables |
| Destination ID, vendor fields, and settings schema | GET /destination, then GET /destination/{id} |
| Brand ID | GET /brand |
| Account ID, if reassigning from the default | GET /account, then GET /account/{id} |
| Timezone ID for a schedule | GET /timezone |
GET /audience-source, GET /external, and GET /brand filter by name with a searchText query parameter. If your integration still sends the older searchTerm parameter on GET /brand, it's silently ignored — switch to searchText. GET /destination and GET /account have no name filter; page through the full list instead.
Next steps​
- Walk through the step-by-step campaign creation and launch sequence. For more information, see Launch an external campaign with automation.
- Understand the campaign lifecycle and error conventions before writing your client. For more information, see How external campaign automation works.