API quickstart

1.Get an API key

In the Mailee app, go to Settings → API keys (owner only), choose the scopes you need, and generate a key. It’s shown once — store it somewhere safe. Keys look like mk_live_… and are scoped to a single workspace.

2.Authenticate

Send your key as a Bearer token on every request. The base URL is https://mailee-ai.web.app/v1.

Authorization: Bearer mk_live_xxx

3.Create your first contact

curl https://mailee-ai.web.app/v1/contacts \
  -H "Authorization: Bearer mk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"email":"ada@example.com","first_name":"Ada","tags":["api"]}'

const res = await fetch("https://mailee-ai.web.app/v1/contacts", {
  method: "POST",
  headers: {
    Authorization: "Bearer mk_live_xxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email: "ada@example.com", first_name: "Ada" }),
});
const { data } = await res.json();

import requests

r = requests.post(
    "https://mailee-ai.web.app/v1/contacts",
    headers={"Authorization": "Bearer mk_live_xxx"},
    json={"email": "ada@example.com", "first_name": "Ada"},
)
print(r.json()["data"])

A successful create returns 201 with { "data": { … } }. Creating a contact whose email already exists updates it and returns 200.

4.Send a transactional email

curl https://mailee-ai.web.app/v1/transactional/send \
  -H "Authorization: Bearer mk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"to":"ada@example.com","subject":"Welcome","html":"<p>Hello!</p>"}'

5.Scopes

Each key carries scopes; a request without the required scope returns 403.

• contacts:read / contacts:write
• lists:read / lists:write
• campaigns:read / campaigns:write / campaigns:send
• transactional:send
• mail:read / mail:write
• webhooks:read / webhooks:write
• events:read

6.Rate limits & pagination

120 requests/minute per key — watch the X-RateLimit-* headers. List endpoints take limit and starting_after; follow meta.next_cursor.

7.Webhooks

Register an endpoint in Settings → API keys → Webhooks (or via POST /v1/webhooks) to receive contact.created, email.delivered/opened/clicked/bounced, and campaign.sent events. Verify each delivery with the X-Mailee-Signature header (HMAC-SHA256 of the raw body using your endpoint’s signing secret).