API reference

Account

Who the key belongs to, how the account is doing, and what to set up next. GET /v1/get-started is the best first call for an agent: it returns the setup checklist and the next step.

The Account object

type Account = {
  id: string;                          // acc_…
  name: string;
  plan: "free" | "starter" | "growth" | "scale" | "custom";
  trust_level: 0 | 1 | 2 | 3 | 4 | 5;  // sets how fast marketing email may go out
  status: "active" | "marketing_paused" | "paused";
  live_enabled: boolean;               // false until a human "goes live"
  spending_cap_cents: number | null;   // marketing only
  timezone: string;
  brand: { product_name: string; logo_url: string | null; primary_color: string; support_email: string | null };
  onboarded: boolean;
  created_at: string;
};

Get the current key

GET/v1/me

Returns the API key making the request and the account it belongs to. A quick way to check a key works.

curl https://api.mailpark.io/v1/me \
  -H "Authorization: Bearer $MAILPARK_API_KEY"

Response · 200

{
  "api_key": {
    "id": "key_8Hq2",
    "name": "Claude Code",
    "prefix": "sk_test_8Hq2",
    "environment": "test",
    "scopes": [
      "emails:send",
      "contacts:write",
      "events:write",
      "templates:write",
      "broadcasts:draft",
      "sequences:write",
      "sequences:activate",
      "webhooks:write",
      "logs:read",
      "domains:write"
    ],
    "created_by": "founder@acme.dev",
    "created_at": "2026-09-02T08:05:00Z",
    "last_used_at": "2026-10-22T10:02:11Z",
    "revoked_at": null
  },
  "account": {
    "id": "acc_demo",
    "name": "Acme",
    "plan": "starter",
    "trust_level": 2,
    "status": "active",
    "live_enabled": true,
    "spending_cap_cents": 5000,
    "timezone": "Europe/London",
    "brand": {
      "product_name": "Acme",
      "logo_url": "https://acme.dev/logo.png",
      "primary_color": "#4f46e5",
      "support_email": "help@acme.dev"
    },
    "onboarded": true,
    "created_at": "2026-09-02T08:00:00Z"
  }
}

▶ Try it in the playground

Get the setup checklist

GET/v1/get-started

The account's setup steps, which are done, and how to do the rest. Agents should call this first.

curl https://api.mailpark.io/v1/get-started \
  -H "Authorization: Bearer $MAILPARK_API_KEY"

Response · 200

{
  "account": {
    "id": "acc_demo",
    "name": "Acme",
    "plan": "starter",
    "trust_level": 2,
    "status": "active",
    "live_enabled": true,
    "spending_cap_cents": 5000,
    "timezone": "Europe/London",
    "brand": {
      "product_name": "Acme",
      "logo_url": "https://acme.dev/logo.png",
      "primary_color": "#4f46e5",
      "support_email": "help@acme.dev"
    },
    "onboarded": true,
    "created_at": "2026-09-02T08:00:00Z"
  },
  "steps": [
    {
      "id": "templates",
      "label": "Add your email templates",
      "done": true,
      "how": "POST /v1/templates/essentials"
    },
    {
      "id": "test_send",
      "label": "Send a test email",
      "done": true,
      "how": "POST /v1/emails with a test key"
    },
    {
      "id": "domain",
      "label": "Verify a sending domain",
      "done": false,
      "how": "POST /v1/domains, add the DNS records, then POST /v1/domains/{id}/verify"
    },
    {
      "id": "go_live",
      "label": "Go live",
      "done": false,
      "how": "A person clicks Go live in the web app"
    }
  ],
  "next_steps": [
    "Add your domain with POST /v1/domains { domain: \"acme.dev\" }."
  ]
}

▶ Try it in the playground

Get account health

GET/v1/health

Bounce and complaint rates over 7 days, trust level and what unlocks the next one, monthly usage, today's marketing limit, held items and anything that needs attention.

Rates and thresholds are fractions: 0.02 is 2%. usage.percent is 0–100.

curl https://api.mailpark.io/v1/health \
  -H "Authorization: Bearer $MAILPARK_API_KEY"

Response · 200

{
  "account_status": "active",
  "live_enabled": true,
  "trust": {
    "level": 2,
    "name": "Starting",
    "marketing_daily_limit": 5000,
    "largest_broadcast": 10000,
    "test_send": "new_audiences"
  },
  "next_unlock": {
    "level": 3,
    "name": "Established",
    "marketing_daily_limit": 25000,
    "requirements": [
      {
        "label": "14 days at Starting",
        "met": false
      },
      {
        "label": "Bounce rate under 2%",
        "met": true
      }
    ]
  },
  "rates": {
    "window_days": 7,
    "sent": 8210,
    "bounced": 41,
    "complained": 1,
    "bounce_rate": 0.005,
    "complaint_rate": 0.0001,
    "bounce_threshold": 0.04,
    "complaint_threshold": 0.001
  },
  "usage": {
    "period": "2026-10",
    "plan": "starter",
    "included": 50000,
    "sent": 21304,
    "transactional_sent": 15990,
    "marketing_sent": 5314,
    "forecast": 30100,
    "overage": 0,
    "overage_cost_cents": 0,
    "percent": 42.6
  },
  "today": {
    "marketing_sent": 820,
    "marketing_limit": 5000,
    "transactional_sent": 611
  },
  "daily": [
    {
      "date": "2026-10-22",
      "transactional": 611,
      "marketing": 820,
      "bounced": 3,
      "complained": 0
    }
  ],
  "held": {
    "broadcasts": 0,
    "messages": 0
  },
  "attention": [],
  "next_steps": []
}

▶ Try it in the playground

List activity

GET/v1/activity

The audit log: who changed what, newest first. Every action taken with an API key is recorded with the key's name.

scope logs:read

Query parameters

actor_typestring
user, api_key, system or admin.
actor_idstring
Only this user or key.
limitinteger
How many to return, 1–100. Default 50.
cursorstring
The next_cursor from the previous page.

curl 'https://api.mailpark.io/v1/activity?actor_type=api_key' \
  -H "Authorization: Bearer $MAILPARK_API_KEY"

Response · 200

{
  "data": [
    {
      "id": "aud_1Zx4",
      "actor_type": "api_key",
      "actor_id": "key_8Hq2",
      "actor_name": "Claude Code",
      "action": "template.updated",
      "target": "password-reset",
      "details": {
        "version": 3
      },
      "created_at": "2026-10-22T10:02:11Z"
    }
  ],
  "next_cursor": null
}

▶ Try it in the playground

Pause marketing

POST/v1/account/pause-marketing

Stops all broadcasts and sequences at once. Transactional email keeps flowing. Use it when something is wrong, such as the wrong content going out or complaints rising. Only a person can resume, in the web app.

Body

reasonstring
Why, in plain words. Shown to the team.

curl -X POST https://api.mailpark.io/v1/account/pause-marketing \
  -H "Authorization: Bearer $MAILPARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Wrong discount code in the October update."
  }'

Response · 200

{
  "id": "acc_demo",
  "name": "Acme",
  "plan": "starter",
  "trust_level": 2,
  "status": "marketing_paused",
  "live_enabled": true,
  "spending_cap_cents": 5000,
  "timezone": "Europe/London",
  "brand": {
    "product_name": "Acme",
    "logo_url": "https://acme.dev/logo.png",
    "primary_color": "#4f46e5",
    "support_email": "help@acme.dev"
  },
  "onboarded": true,
  "created_at": "2026-09-02T08:00:00Z"
}

▶ Try it in the playground

PreviousAI agents and MCP NextEmails