Quickstart

Send your first email in under five minutes. This guide walks you through creating an API key, sending an email, and checking its delivery status.

Prerequisites

• A Krafter Mail account (invite-only -- request access at app.krafter.dev)
• A verified sending domain (or use the shared sandbox domain for testing)

Step 1: Get Your API Key

1. Log in to the Krafter Mail dashboard.
2. Navigate to Settings > API Keys.
3. Click Create API Key and give it a descriptive name (e.g., "Production Backend").
4. Select the scopes you need. For sending emails, you need at least mail:send.
5. Copy the generated key. It starts with kr_live_ and will only be shown once.

WARNING

Store your API key securely. Do not commit it to version control or expose it in client-side code.

Step 2: Send Your First Email

Make a POST request to the emails endpoint with your API key in the Authorization header:

curl -X POST https://app.krafter.dev/api/v1/emails \
  -H "Authorization: Bearer kr_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@yourdomain.com",
    "to": ["recipient@example.com"],
    "subject": "Hello from Krafter Mail",
    "html": "<h1>Welcome!</h1><p>Your first email sent via Krafter Mail.</p>",
    "stream": "transactional"
  }'

The stream field selects either transactional or broadcast. If your API key allows exactly one stream, you can omit it; if it allows both, stream is required.

You will receive a response with the email ID and status:

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "from": "hello@yourdomain.com",
    "to": ["recipient@example.com"],
    "cc": [],
    "bcc": [],
    "reply_to": null,
    "subject": "Hello from Krafter Mail",
    "status": "queued",
    "tags": {},
    "scheduled_at": null,
    "sent_at": null,
    "delivered_at": null,
    "opened_at": null,
    "clicked_at": null,
    "bounced_at": null,
    "complained_at": null,
    "error_reason": null,
    "created_at": "2026-01-15T10:30:00Z"
  }
}

Avoiding duplicate sends

Pass an Idempotency-Key header with a unique value (for example a UUID generated by your app). If the same key is replayed within 24 hours, the original email is returned and no duplicate send is created:

curl -X POST https://app.krafter.dev/api/v1/emails \
  -H "Authorization: Bearer kr_live_abc123def456" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "from": "hello@yourdomain.com",
    "to": ["recipient@example.com"],
    "subject": "Order #4242 confirmation",
    "html": "<p>Thanks for your order!</p>",
    "stream": "transactional"
  }'

Step 3: Check Delivery Status

Use the email ID (a UUID) from the previous response to check the delivery status:

curl https://app.krafter.dev/api/v1/emails/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer kr_live_abc123def456"

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "from": "hello@yourdomain.com",
    "to": ["recipient@example.com"],
    "subject": "Hello from Krafter Mail",
    "status": "delivered",
    "created_at": "2026-01-15T10:30:00Z",
    "sent_at": "2026-01-15T10:30:01Z",
    "delivered_at": "2026-01-15T10:30:02Z"
  }
}

Step 4: View Events Timeline

To see the full lifecycle of an email, including open and click events, fetch its event timeline:

curl https://app.krafter.dev/api/v1/emails/550e8400-e29b-41d4-a716-446655440000/events \
  -H "Authorization: Bearer kr_live_abc123def456"

{
  "data": [
    {
      "type": "queued",
      "timestamp": "2026-01-15T10:30:00Z"
    },
    {
      "type": "sent",
      "timestamp": "2026-01-15T10:30:01Z"
    },
    {
      "type": "delivered",
      "timestamp": "2026-01-15T10:30:02Z"
    },
    {
      "type": "opened",
      "timestamp": "2026-01-15T10:31:15Z",
      "metadata": {
        "user_agent": "Mozilla/5.0",
        "ip": "203.0.113.42"
      }
    }
  ]
}

Next Steps

• Set up authentication and understand API key scopes
• Add a sending domain for production use
• Configure webhooks to receive real-time delivery notifications
• Use SMTP relay if you prefer SMTP over REST