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

# Introduction

> Get started with the Ecomail API v2.0

The Ecomail API v2.0 lets you programmatically manage your email marketing — lists, subscribers, campaigns, automations, and more.

<Card title="Download the OpenAPI spec" icon="download" href="/openapi.json" horizontal>
  Machine-readable OpenAPI 3.1 description of the whole API. Import it into Postman or Insomnia, or use it to generate client SDKs.
</Card>

## Base URL

All API requests use the following base URL:

```
https://api2.ecomailapp.cz/
```

## Authentication

Before using the API, you need an API key. To obtain one:

1. Log in to your Ecomail account
2. Go to **Manage your account** → **For developers**
3. Click **Copy API Key**

Every request must include a `key` header containing your API key:

```bash theme={null}
curl https://api2.ecomailapp.cz/lists \
  -H "key: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

<Warning>
  Keep your API key secret. Do not expose it in client-side code or public repositories.
</Warning>

### Required headers

| Header         | Value              |
| -------------- | ------------------ |
| `key`          | Your API key       |
| `Content-Type` | `application/json` |

## CORS and security restrictions

For security reasons, the API **does not accept direct HTTP requests from JavaScript/AJAX in a browser**. Attempting to call the API from a frontend application results in a CORS (Cross-Origin Resource Sharing) error.

JavaScript runs client-side, meaning API requests made directly from a browser would expose your API key. Always send API requests **from a backend server** where your API key is safely stored. Do not expose API requests in client-side code to prevent key leaks.

If you need to access the API from a web application, route requests through your **backend server** to handle authentication securely.

## Rate limiting

The API allows up to **1,000 requests per minute** per API key. If you exceed this limit, the API returns a `429 Too Many Requests` status code with a `Retry-After` header indicating how many seconds to wait before retrying.

## Response format

All responses are returned as JSON. Successful responses return the requested data directly. Error responses include an appropriate HTTP status code.