# Management API

Provision Email Bump account structure programmatically. The Management API is designed for agents and CLIs that onboard projects without a person clicking through the dashboard.

Base URL: `https://emailbump.com/api/v1`

## Authentication

Authenticate with an **all-access key** — a key created with the "all access" scope (via `emailbump login`, or **Developers → API Keys → All-access keys**). A project-scoped key can't reach these endpoints. See [Authentication](https://emailbump.com/docs/api-keys). Send it as a Bearer token:

```http
Authorization: Bearer ebk_all_access_key
```

Management calls are logged under **Developers → API Keys → Account API calls**. Each entry records the token, path, response status, and latency.

## Workspaces

```http
GET /v1/workspaces
POST /v1/workspaces
```

A workspace is the billing boundary. Creating one also creates a same-named starter project on the free plan and returns both resources.

### Create a workspace

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | Display name for the workspace. |

```bash
curl -X POST https://emailbump.com/api/v1/workspaces \
  -H "Authorization: Bearer ebk_all_access_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Agency" }'
```

```json
{
  "workspace": {
    "id": "b1c2…",
    "name": "Acme Agency",
    "slug": "acme-agency-3f9a2b"
  },
  "project": {
    "id": "7a10…",
    "workspace_id": "b1c2…",
    "name": "Acme Agency",
    "slug": "acme-agency-3f9a2b"
  }
}
```

`GET /v1/workspaces` returns each workspace with its projects.

## Projects

```http
POST /v1/projects
```

A project is a sending unit inside a workspace with its own contacts, campaigns, domains, and keys. Every workspace starts with one project; use this endpoint to add more.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `workspace_id` | string | Yes | Workspace that will own the project. |
| `name` | string | Yes | Project display name. |

```bash
curl -X POST https://emailbump.com/api/v1/projects \
  -H "Authorization: Bearer ebk_all_access_key" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "b1c2…",
    "name": "Acme Newsletter"
  }'
```

## Flows

```http
POST /v1/projects/{project_id}/flows
```

Create an active **new contact → send one email** flow. Use the built-in `welcome` template or provide a custom `subject` and `html`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `template` | string | Conditional | Use `welcome` for the built-in welcome email. |
| `name` | string | No | Dashboard name. Defaults to `Welcome`. |
| `subject` | string | Conditional | Required with a custom email. |
| `html` | string | Conditional | Custom email content, wrapped in MJML. |

Provide either `template: "welcome"` or both `subject` and `html`.

```bash
curl -X POST https://emailbump.com/api/v1/projects/7a10…/flows \
  -H "Authorization: Bearer ebk_all_access_key" \
  -H "Content-Type: application/json" \
  -d '{ "template": "welcome" }'
```

```json
{ "flow_id": "c4d5…" }
```

## Project API keys

```http
POST /v1/projects/{project_id}/api-keys
```

Mint a project-scoped `ebk_` key for sending email and using project APIs. The secret is returned once.

```bash
curl -X POST https://emailbump.com/api/v1/projects/7a10…/api-keys \
  -H "Authorization: Bearer ebk_all_access_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "server" }'
```

## Sending domains

```http
POST /v1/projects/{project_id}/domains
GET /v1/projects/{project_id}/domains/{domain_id}
```

Add a sending domain and receive the DNS records that must be published. Poll the GET endpoint to check verification.

```bash
curl -X POST https://emailbump.com/api/v1/projects/7a10…/domains \
  -H "Authorization: Bearer ebk_all_access_key" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "mail.acme.com" }'
```

## Typical agent onboarding

1. Create a workspace and read the starter project ID from the response.
2. Seed a welcome flow for the project.
3. Add a sending domain and publish the returned DNS records.
4. Poll the domain endpoint until verification completes.
5. Mint a project API key and store the secret securely.

All-access keys have account-wide authority: provisioning, plus acting in any project you admin (via `X-Project-Id`). Keep them in server-side environment variables or a secrets manager, use separate keys per agent or environment, set expirations, and rotate exposed credentials immediately.