Senda

Open-source email orchestration for multi-tenant SaaS

Templates, inheritance, environment-aware delivery, and embeddable builder flows — one platform.

Documentation · API Reference · Quick Start · Contributing

Why Senda?

Most email products are either too simple for multi-tenant SaaS or too operationally heavy. Senda stays in the middle:

• PostgreSQL-first — queue, cache, rate limiting, and state all stay close to the core application. No Redis required.
• Hierarchical resolution — global, tenant, _system, and workspace cooperate through explicit inheritance and selective sharing.
• Real environments — each logical workspace operates as prod and test, with isolated API keys, runtime state, and safety controls.
• Embeddable — external builder/editor surfaces can be exposed through custom auth methods and workspace resolvers.
• SDK-friendly — embedders can register code injectors, per-request init, external auth/resolver seams, and lifecycle hooks without forking Senda.

Features

Environment model

Each logical workspace has two physical operational environments:

• prod
• test

Important rules:

• The send ref stays tenant:workspace:templateType.
• Environment is selected by route, API key prefix, or external header, depending on the surface.
• Test-only runtime reset is exposed on the environment-scoped management surface.
• Test-only recipient safety controls exist at workspace level and can be overridden by template type in the test environment.

See docs/API.md and skills/senda/ for the operational details.

Shared adapters from tenant _system

Senda supports selective sharing from a tenant _system workspace:

• Gmail sharing is adapter-level.
• SES sharing is email-identity-level; domain identities are not shareable.
• Shared entries are read-only in child workspaces.
• Child workspaces can fork inherited template content when they need local ownership.

Quick Start

Prerequisites: Docker, Go 1.25+, Node 25 (or web/.nvmrc), Make, Corepack.

git clone https://github.com/rendis/senda.git
cd senda
corepack enable
(cd web && corepack install)
pnpm --dir web install
make dev
curl http://localhost:8081/health

make dev now starts the Docker services and the Next.js frontend together. If you only want the Docker services, use make dev-stack.

Example data-plane send:

curl -X POST http://localhost:8081/api/v1/send \
  -H "Authorization: Bearer senda_prod_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ref": "acme:main:welcome-email",
    "to": ["user@example.com"],
    "variables": {"name": "Jane"},
    "locale": "es"
  }'

For local validation, prefer the repo gates used by CI:

make ci-backend-pr
make ci-frontend      # if you changed web/
make ci-pr            # backend + frontend
make ci-taxonomy-check # docs/workflows/Makefile drift guard
make install-githooks

Use as a Library

Senda exposes a public Go SDK for embedders.

go get github.com/rendis/senda

package main

import (
    "context"
    "github.com/rendis/senda/sdk"
)

func main() {
    engine := sdk.NewWithConfig("config.yaml")

    engine.SetInitFunc(func(ctx context.Context, injCtx *sdk.InjectorContext) (any, error) {
        return loadStudent(ctx, injCtx.Header("X-Case-Id"))
    })

    engine.RegisterInjector(&StudentInjector{})
    engine.RegisterExternalAuthMethod(&PortalAuthMethod{})
    engine.RegisterExternalWorkspaceResolver(&PortalWorkspaceResolver{})

    engine.OnStart(func(ctx context.Context) error { return connectMongo(ctx) })
    engine.OnShutdown(func(ctx context.Context) error { return closeMongo(ctx) })

    _ = engine.Run()
}

Public extension seams:

• RegisterInjector(...)
• SetInitFunc(...)
• RegisterExternalAuthMethod(...)
• RegisterExternalWorkspaceResolver(...)
• OnStart(...)
• OnShutdown(...)

InjectorContext.Environment() and ExternalIntegrationRequest.Environment are the public runtime sources of truth for prod / test behavior.

External integrations

Senda exposes an embeddable external surface under:

• /api/v1/external/:profile_slug/bootstrap
• /api/v1/external/:profile_slug/environments/:environment/bootstrap
• /api/v1/external/:profile_slug/tenants/:tenant_code/workspaces/:workspace_code/...

External authenticated requests must include:

X-Senda-Environment: prod|test

External profiles select a registered auth method and workspace resolver, which together determine effective permissions and effective workspace.

API at a glance

MCP integration

Senda ships a dedicated MCP skill and OpenAPI-backed MCP server configuration.

• Skill bundle: skills/senda/
• Setup guide: docs/mcp_setup.md
• OpenAPI-backed server name: senda

For data-plane MCP usage, authenticate with a raw workspace API key such as senda_prod_... or senda_test_....

Development

Project structure

senda/
├── sdk/                    Public SDK
├── cmd/senda/              Server entry point
├── internal/
│   ├── domain/             Domain model and environment types
│   ├── port/               Public extension and internal contracts
│   ├── service/            Business logic
│   ├── resolution/         Scope and injector resolution
│   ├── adapter/            Postgres, River, SES, Gmail, SMTP, MJML, crypto
│   ├── http/               Handlers and middleware
│   └── app/                Bootstrap and extension bridge
├── migrations/             SQL migrations
├── docs/                   Human-facing docs
├── skills/senda/           Self-contained skill bundle for agents
└── web/                    Next.js frontend