REST API

The Alpaco REST API allows you to programmatically inspect workspaces, compile designs, and push finalized email assets directly to your external distribution channels.

Base Configuration & Auth

All API requests must be made over HTTPS and authenticated using your organization-level JSON Web Token (JWT). Each user can generate a JWT token on their profile page

Base URL: https://platform.alpaco.email/api/mcp/v1/

Authentication Header: Bearer <your_organization_jwt>

Authorization: Bearer YOUR_ORGANIZATION_JWT
Content-Type: application/json
Accept: application/json

Endpoint Lifecycle Matrix

Description	Endpoint	Method
Retrieves active workspace brand identities, target audiences, and copywriting rules.	/brand/guidelines	GET
Lists all active templates with their block keys and allowed inputs.	/templates	GET
Searches for existing approved graphics, logos, and banners in your media library.	/assets?search={keyword}	GET
Compiles a brand-new design layout into a fresh HTML draft asset and returns a unique id.	/assemble	POST
Fetches the current raw JSON configuration tree state of a saved email layout draft.	/assemble/{email_id}	GET
Updates and re-compiles an existing email draft asset for seamless content iterations.	/assemble/{email_id}	POST
Retrieves active third-party ESP/CRM integration connection IDs (HubSpot, Braze, etc.).	/connections	GET
Pushes a finalized, compiled email design straight into your external marketing platform.	/export	POST

Getting Started

Unlike traditional, rigid APIs that force you to memorize hundreds of syntax rules, the Alpaco API is discovery-driven and self-correcting.

You do not need a static instruction guide for every email layout in your workspace. Instead, you dynamically query our engine to find your template constraints, construct your payload, and rely on our real-time validation engine to guide you through any structural mistakes.:

Phase 1: Inspect

Before your code can assemble an email, it needs to know what layouts are valid in your specific workspace. You do this by calling the templates directory.

• The Endpoint: GET /templates

• The Goal: Capture your target template_id and read the available_blocks array.

Look closely at the response. The API will explicitly tell you what block components are allowed (e.g., article, products) and the exact array keys (header_text, body_text) those blocks require. Your application holds these keys in memory to map your raw data correctly.

Phase 2: Listen

Once your application maps out the text, images, and layout choices, you shoot your composition payload to the compilation track.

• The Endpoint: POST /assemble

• The Goal: Render your raw JSON into bulletproof HTML markup.

If your code passes a typo (like writing bodycopy instead of body_text), or forgets a global parameter like the marketing subjectline, the Alpaco compiler will instantly stop and hand you a 422 Unprocessable Entity response containing a highly explicit error path.

Example of error response

{
  "success": false,
  "errors": {
    "design.blocks.0.values": "Invalid keys: [bodycopy]. Allowed keys for block 'article': [header_text, body_text]"
  }
}

You don't need a manual to troubleshoot your formatting. Simply read the errors object. It acts as a real-time code reviewer, telling you exactly which array index failed and providing a list of allowed alternative keys to fix your script instantly.

Phase 3: Scale

When your payload clears the validator, the engine returns a successful response alongside a unique, tracked asset number.

• The Output: A unique, persistent database integer identifier (e.g., "id": 771024).

Chaining your next actions:

Once you have this tracking ID, you can interact with the layout indefinitely using simple lifecycle combinations:

1. Content Iterations (GET /assemble/{id}) and (POST /assemble/{id}): If an automated process or reviewer needs to adjust a headline later, you don't generate a new orphan draft. You run an update request against that exact asset ID, passing the entire content back with adjustments.

2. Platform Syncing (POST /export): When the campaign is perfect, pass the email id alongside your esp_connection_id to cleanly push the final layout directly into your email sending account, connected to your organization in Alpaco.