> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alpacarelay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Developers overview

> Generate emails from your own code, or let an AI assistant work in your workspace, using the same engine as the app.

AlpacaRelay has two developer interfaces, and they do different amounts:

> [card] [REST API](https://docs.alpacarelay.com/developers/generate-an-email.md)
>
> `POST /api/v1/emails` does one thing: **generate a complete, ready-to-send email from a prompt**. Call it from your own code. The result streams over Server-Sent Events.

> [card] [MCP server](https://docs.alpacarelay.com/developers/mcp/introduction.md)
>
> 46 tools for Claude, ChatGPT, Cursor, VS Code, Codex, and other MCP clients. **Generate and edit emails, manage contacts and segments, read analytics, and build campaigns.**

Generation is the same in both: same engine as the app, same credits, same output. Everything beyond generation is MCP-only.

Both use the same workspace, so they also share one set of rules. **Essentials** ([Authentication](https://docs.alpacarelay.com/developers/authentication.md), [Credits and limits](https://docs.alpacarelay.com/developers/limits.md), and [Errors](https://docs.alpacarelay.com/developers/errors.md)) applies to both. The **REST API** and **MCP** sections only cover what differs.

## What it is not

Here's the scope up front, so you don't go looking for endpoints that aren't there:

> [!WARNING]
>
> Neither interface **sends** a campaign. Over MCP an assistant can build a campaign up to the point of sending, but sending is done in the app. The REST API generates emails and nothing else. It has no endpoints for contacts, campaigns, or analytics.

To send what you generate, [export the design to your ESP](https://docs.alpacarelay.com/integrations/overview.md) or [send a campaign from AlpacaRelay](https://docs.alpacarelay.com/get-started/connect-a-sending-identity.md).

## Base URL and reference

| | |
| - | - |
| Base URL | `https://app.alpacarelay.com` |
| REST endpoint | `POST /api/v1/emails` |
| MCP endpoint | `https://app.alpacarelay.com/api/mcp` |
| OpenAPI spec | [`/api/v1/openapi.json`](https://app.alpacarelay.com/api/v1/openapi.json) |
| Interactive reference | [`app.alpacarelay.com/docs`](https://app.alpacarelay.com/docs) |

The interactive reference is generated from the OpenAPI spec, so it's always in step with the running API. Use it to read exact schemas and try calls; use these pages for the surrounding explanation.

## Generate a client

The spec is OpenAPI 3.1 and served publicly, so you can generate a typed client rather than hand-rolling one:

```bash theme={null}
npx @openapitools/openapi-generator-cli generate \
  -i https://app.alpacarelay.com/api/v1/openapi.json \
  -g typescript-fetch \
  -o ./alpacarelay-client
```

> [!NOTE]
>
> A generated client will model the request correctly, but most generators treat the response as a plain string, because it's an SSE stream rather than a JSON body. You'll still want to parse the event stream yourself — see [Generate an email](https://docs.alpacarelay.com/developers/generate-an-email.md) for a worked example.

## Get started

**1. Get credentials**

For REST, create an API key under **Settings** → **API keys** (workspace owners only). For MCP, you can [sign in with OAuth](https://docs.alpacarelay.com/developers/mcp/connect.md#sign-in) instead. See [Authentication](https://docs.alpacarelay.com/developers/authentication.md).

**2. Make your first call**

Either [call the REST endpoint](https://docs.alpacarelay.com/developers/generate-an-email.md) or [connect the MCP server](https://docs.alpacarelay.com/developers/mcp/connect.md) to your editor.

**3. Know the limits**

One credit per generation, 60 calls a minute, three concurrent generations per workspace. See [Credits and limits](https://docs.alpacarelay.com/developers/limits.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.