> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runnage.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Product Strategy

> How Runnage should become a developer-first email and SMS API for African teams

Runnage should win by being the fastest way for African startups to ship reliable customer communication across email and SMS, while keeping the API simple enough for a developer to adopt in minutes.

## Positioning

Lead with a focused promise:

> Send transactional email and SMS across Africa with one developer-first API.

This separates Runnage from email-only products by making SMS a first-class channel and from generic SMS gateways by treating developer experience, observability, teams, webhooks, and deliverability as core product features.

## Product principles

<CardGroup cols={2}>
  <Card title="One API, two channels" icon="code">
    Email and SMS should share authentication, idempotency, logs, webhooks,
    team permissions, and API conventions, while keeping channel-specific
    delivery details explicit.
  </Card>

  <Card title="Africa-first delivery" icon="globe-africa">
    Optimize around local sender IDs, country routing, local currency billing,
    carrier constraints, compliance, and regional deliverability guidance.
  </Card>

  <Card title="Debuggable by default" icon="magnifying-glass-chart">
    Every send should produce a searchable event trail with request metadata,
    provider responses, normalized statuses, and webhook replay support.
  </Card>

  <Card title="Provider portable" icon="route">
    Keep AWS SES, Arkesel, and future providers behind internal interfaces so
    Runnage can route by country, cost, deliverability, and failover policy.
  </Card>
</CardGroup>

## MVP API surface

Start with a compact REST API that developers can memorize:

| Area       | Endpoint shape    | Purpose                                                      |
| ---------- | ----------------- | ------------------------------------------------------------ |
| Email      | `POST /v1/emails` | Send one transactional email                                 |
| SMS        | `POST /v1/sms`    | Send one transactional SMS                                   |
| Domains    | `/v1/domains`     | Verify sending domains and DNS records                       |
| Sender IDs | `/v1/sender-ids`  | Register and manage SMS sender IDs                           |
| Events     | `/v1/events`      | Search normalized delivery events                            |
| Webhooks   | `/v1/webhooks`    | Subscribe to delivery, bounce, complaint, and inbound events |
| API keys   | `/v1/api-keys`    | Issue scoped keys for servers and CI                         |

Add batch sends, broadcasts, templates, contacts, and inbound routing only after the transactional path is excellent.

## Developer experience checklist

<Steps>
  <Step title="Make the first send copy-pasteable">
    Publish examples for cURL, Go, Node.js, Python, PHP, and Laravel. The first
    successful request should require only an API key, sender, recipient, and
    content.
  </Step>

  <Step title="Ship official SDKs from the API contract">
    Treat OpenAPI as the source of truth and generate typed SDKs. Hand-polish the
    Go SDK first because the backend is Go and many African fintech and infra
    teams use Go for services.
  </Step>

  <Step title="Normalize errors and events">
    Return stable error codes such as `invalid_sender`, `domain_not_verified`,
    `insufficient_balance`, `rate_limited`, and `provider_unavailable` instead
    of exposing provider-specific failures.
  </Step>

  <Step title="Document deliverability as product">
    Provide domain setup, DKIM/SPF/DMARC, SMS sender ID registration, country
    coverage, content rules, and troubleshooting guides.
  </Step>
</Steps>

## Go engineering approach

Use the current Go service boundaries as the foundation:

* Keep `internal/email` and `internal/sms` provider interfaces small and stable.
* Add a `message_events` storage model before scaling provider integrations.
* Make every send operation idempotent using an `Idempotency-Key` header.
* Introduce a queue-backed worker for retries, scheduled sends, webhook delivery, and provider failover.
* Add structured logs and request IDs across HTTP handlers, provider calls, and webhooks.
* Version all public endpoints under `/v1` before external SDKs are released.

## Suggested build order

1. Transactional email send with verified domains, event logs, and webhooks.
2. Transactional SMS send with sender IDs, country routing, and delivery receipts.
3. Unified logs dashboard and API request inspection.
4. API key scopes, team roles, usage limits, and billing controls.
5. SDKs, CLI, examples, and AI-readable documentation.
6. Templates, batch sending, contacts, broadcasts, and inbound messaging.

## AI-readable docs

Expose an `llms.txt` file and Markdown endpoint index so AI coding tools can understand Runnage quickly. Include product overview, authentication, endpoint list, SDK links, examples, rate limits, error codes, webhook events, and deliverability guides.