Developers

Management API

Provision workspaces, projects, sending domains, and project keys programmatically — for agents and CLIs.

Overview

The Management API provisions your account structure programmatically: create workspaces (each comes with a starter project), add more projects, seed automated flows, add and verify sending domains, and mint project API keys. It's designed for agents and CLIs that onboard new projects without a person clicking through the dashboard.

Everything is logged

Management calls appear under Developers → API Keys → Account API calls for you, and in the admin console cross-tenant. Each row shows the token name, path, status, and latency.

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.

HTTP

Authorization: Bearer ebk_all_access_key

Workspaces

GET/v1/workspaces

POST/v1/workspaces

A workspace is the billing boundary. Creating one also creates a same-named starter project inside it (on the free plan) and returns both — so you can start sending right away. Use Projects to add more projects to a workspace.

Create — body parameters

namestringrequired

Display name for the new workspace.

cURL

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" }'

200 response

{
  "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 lists your workspaces, each with its projects:

GET /v1/workspaces

{ "data": [ { "workspace": { … }, "projects": [ { … } ] } ] }

Projects

POST/v1/projects

A project is a sending unit inside a workspace (its own contacts, campaigns, domains, and keys). Every workspace starts with one project; use this to add more projects to a workspace. Creating a project just creates the project — add automated flows separately with the Flows endpoint.

Body parameters

workspace_idstringrequired

The workspace to create the project in.

namestringrequired

Project name.

cURL

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"
  }'

200 response

{
  "project": {
    "id": "7a10…",
    "workspace_id": "b1c2…",
    "name": "Acme Newsletter",
    "slug": "acme-newsletter-3f9a2b"
  }
}

Flows

POST/v1/projects/{project_id}/flows

Create an automated flow for a project. Today this creates a new contact → send one email flow (active immediately). Use the built-in welcome template, or supply your own subject and html for a custom greeting.

Body parameters

templatestringoptional

Use "welcome" to seed the built-in welcome email. Currently the only template.

namestringoptional

Flow name shown in the dashboard. Defaults to "Welcome".

subjectstringoptional

Subject line for the sent email. Required if you don't pass a template.

htmlstringoptional

Simple HTML/text for the email body (wrapped in MJML). Required if you don't pass a template.

Provide a template or a custom email

Send either template: "welcome" or a subject + html pair. A request with neither returns 400.

Built-in welcome

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" }'

Custom welcome

curl -X POST https://emailbump.com/api/v1/projects/7a10…/flows \
  -H "Authorization: Bearer ebk_all_access_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Onboarding",
    "subject": "Welcome to Acme",
    "html": "<b>Thanks for joining!</b> Here's how to get started…"
  }'

200 response

{ "flow_id": "c4d5…" }

Project keys

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

Mint a project-scoped ebk_ key so the new project can send email and use the rest of the API. The secret is returned once.

Body parameters

namestringrequired

A name for the key (shown in the project's activity log).

cURL

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" }'

Domains

POST/v1/projects/{project_id}/domains

GET/v1/projects/{project_id}/domains/{domain_id}

Add a sending domain to a project and get back the DNS records to publish. Poll the GET endpoint to check verification status.

Add — body parameters

domainstringrequired

The domain to send from, e.g. mail.acme.com.

cURL

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" }'

End-to-end example

A typical agent onboarding: a workspace (with its starter project), a welcome flow, a sending domain, and a project key.

bash

TOKEN=ebk_all_access_key
BASE=https://emailbump.com/api/v1

# 1. Create a workspace — the response includes its starter project
RESP=$(curl -s -X POST $BASE/workspaces -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"name":"Acme Agency"}')
PROJ=$(echo "$RESP" | jq -r .project.id)
# (need more than one project? POST $BASE/projects with the workspace id.)

# 2. Seed a welcome flow (new contact → send)
curl -s -X POST $BASE/projects/$PROJ/flows -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"template":"welcome"}'

# 3. Add a sending domain (returns DNS records to publish)
curl -s -X POST $BASE/projects/$PROJ/domains -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"domain":"mail.acme.com"}'

# 4. Mint a project key for the app to send with
curl -s -X POST $BASE/projects/$PROJ/api-keys -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"name":"server"}' | jq -r .key