How do I authenticate with the API?

Create an API key from the dashboard, then send it as a Bearer token in the Authorization header for every request. Keys can be scoped and rotated at any time.

Which generation endpoints are available?

Use POST /api/v1/emails/generate for one cold email draft. Sequence review and multi-step workflows belong inside the signed-in account experience.

How are webhooks managed?

Approved paid accounts can register webhook URLs for generation, credit, rate-limit, and usage events from the account workflow.

API reference

Build with Folderly message generation endpoints.

Use the REST API for one server-side cold email draft, then keep save, history, billing, and review workflows inside the simplified authenticated app.

Quick start

One authenticated request.

Generate a single draft with a Bearer token. API keys should stay on your server.

curl -X POST https://generate.folderly.com/api/v1/emails/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "persona": "Head of Sales",
    "offer": "deliverability-aware cold email creation",
    "goal": "book a 15-minute call",
    "tone": "professional"
  }'

Authentication

Send API keys as `Authorization: Bearer YOUR_API_KEY` from backend code only.

Generation

The public v1 path starts with one deliverability-aware draft. Sequence automation stays deferred while the workspace remains focused.

Compatibility

Existing `/api/generate` clients remain separate from this v1 reference.

Endpoints

Core v1 routes.

Create API key

POST/api/v1/emails/generate5 credits

Generate one email

Creates one cold email draft with subject, body, and basic quality evaluation.

Requires persona, offer, and goal.
Tone defaults to professional when omitted.
Use this endpoint for single-message workflows.

Request

{
  "persona": "string (required)",
  "offer": "string (required)",
  "goal": "string (required)",
  "tone": "string (optional)",
  "industry": "string (optional)",
  "additionalContext": "string (optional)"
}

Response

{
  "success": true,
  "data": {
    "emailContent": "Hi [Name], ...",
    "subjectLine": "Quick idea for your outbound pipeline",
    "evaluation": {
      "spamScore": 2.5,
      "toneAnalysis": "professional",
      "effectiveness": "High"
    },
    "metadata": {
      "generationTime": 1234,
      "model": "configured-model",
      "cached": false
    }
  },
  "meta": {
    "credits_used": 5,
    "processing_time_ms": 1234
  }
}

GET/api/v1/account/usage0 credits

Read API usage

Returns account usage, remaining credits, and endpoint-level activity for the current API key.

Requires a valid Bearer token.
Use this to show usage inside an integration or internal dashboard.

Response

{
  "success": true,
  "data": {
    "current_period": {
      "start_date": "2026-05-01T00:00:00.000Z",
      "end_date": "2026-05-31T00:00:00.000Z",
      "api_calls": 42,
      "credits_used": 125,
      "rate_limit_hits": 0
    },
    "daily_breakdown": [],
    "endpoint_usage": {
      "/emails/generate": {
        "calls": 25,
        "credits": 125,
        "avg_response_time_ms": 1234
      }
    },
    "tier_info": {
      "current_tier": "developer",
      "monthly_limit": 1000,
      "remaining_credits": 875
    }
  }
}

Webhooks

Account-managed events.

Approved paid accounts can register webhook delivery URLs for events such as email.generated, credits.low, rate_limit.exceeded, and usage.milestone. Keep webhook setup tied to account key management and internal review workflows.

{
  "url": "https://your-app.com/webhooks/folderly",
  "events": ["email.generated", "credits.low"],
  "description": "Approved account workflow",
  "active": true
}

Account routes

Key management stays signed in.

API key creation and rotation use signed-in account routes: `/api/v1/keys`, `/api/v1/keys/:keyId`, and the account UI. Newly created keys are only shown once.

Read quickstart API overview

Support

Need integration help?

For custom workflows, share the endpoint, request shape, and response issue so support can reproduce it quickly.

Contact support View pricing