Start
Authentication
One workspace key calls Email Marketing, transactional email, Post Scheduling, the Knowledge Vault, and MCP. The key is bound to one organization.
Base URL
Production requests go to https://api.thealtermeai.com. Email paths start with /api/v1/email. Scheduling paths start with /api/v1/scheduling. Knowledge Vault paths start with /api/v1/knowledge. MCP is POST /mcp on the same host.
Create a key
Sign in, open the workspace, then Workspace → API keys. Name the key and tick the scopes it needs. The secret is shown once. Store it then. We only keep a hash. Later, use Edit on a key to change scopes — the secret stays the same.
Send it as Authorization: Bearer emk_…. A missing, revoked, expired, or unknown key returns 401 with code UNAUTHORIZED. The message does not say which of those it was.
One organization per key
The organization is taken from the key. Do not send a profile id header to switch brands. Create a separate key for each organization.
What a call is allowed to do
Creating a campaign or a post group saves a draft. It does not mail anyone and it does not publish. POST /api/v1/email/campaigns/{id}/send sends the campaign. POST /api/v1/scheduling/post-groups/{id}/confirm puts the post on the calendar and charges the schedule fee. POST /api/v1/email/messages sends transactional mail to the addresses in the body. Listing and reading Knowledge Vault entries does not spend AI tokens. Search does, and so does indexing after you add or change an entry.
Scopes
A key only holds the scopes you select. * grants every scope, including scopes added later. A missing scope returns 403. Unknown scope names are rejected when the key is created, so a typo does not look like a permission you have.
Email Marketing
- audiences:read
- audiences:write
- contacts:read
- contacts:write
- campaigns:read
- campaigns:write
- templates:read
- templates:write
- conversions:read
- conversions:write
- webhooks:read
- webhooks:write
- forms:read
- journeys:read
Transactional email
- messages:read
- messages:write
Post Scheduling
- schedule:read
- schedule:write
Knowledge Vault
- vault:read
- vault:write
* stands in for the full set.
Email sending status
GET /api/v1/email/organization needs no extra scope. Any valid key can call it. It returns the organization, the key’s name and scopes, the brand's free email allowance, and each sending domain's state. Scheduling and the vault do not have a separate status call.
/api/v1/email/organizationAny valid keycurl -sS https://api.thealtermeai.com/api/v1/email/organization \
-H "Authorization: Bearer emk_YOUR_KEY"Rate limits
The default is 120 requests per minute per key, shared across REST and MCP. Successful REST responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. When the window is full, REST returns 429 with code RATE_LIMITED and a Retry-After header. MCP uses the same window and returns code RATE_LIMIT.
Errors
| error | A short message you can show to a developer. |
|---|---|
| code | A stable string such as VALIDATION, UNAUTHORIZED, or FORBIDDEN. |
Email refusals that come from the sending allowance, a daily cap, or domain warm-up are listed on Limits and warm-up.