Skip to main content

email-service

email-service sends Shellui mail. Identity, storage, and hosting call it when something happens. A company chooses Resend or SMTP, then decides which events send a message.

The HTTP API lives at https://email.shellui.com. These pages are published at docs.shellui.com/email.

What email-service is​

email-service is the Shellui mail API. It keeps a catalog of events, a queue per lane, and the company's provider credentials. The same process serves the API, Django admin, and OpenAPI.

It is a Django app, published as the shellui/email-service Docker image. It checks JSON Web Tokens (JWTs) issued by identity-service for admin calls. Service-to-service calls use an esk_ key. It does not sign people in itself.

Company-owner routes that Shellui MCP agents may call are listed in Shellui MCP. The OpenAPI schema marks them with an x-mcp extension.

Who it is for​

Use it when a Shellui product needs mail: a sign-in link, an invitation, a notice after a storage or hosting event, a broadcast, or a newsletter. Company owners set the provider, the email rules, and the copy. Operators run the process, Postgres, and Redis.

Your product stays in the shell. email-service does not replace identity-service, storage-service, or hosting-service.

Where it sits​

On the full Shellui stack, three services call email-service when EMAIL_SERVICE_API_KEY is set:

  • identity-service sends sign-in mail and invitations, and forwards other identity events
  • storage-service forwards storage events
  • hosting-service forwards hosting events

email-service then hands the message to Resend or SMTP. The company brings that account. A platform fallback covers Shellui's own mail, and auth mail, when a company has no provider.

Supabase Auth and Supabase Storage do not call email-service. hosting-service still can. The picture is on shellui.com/architecture.

How a call becomes mail​

There are two entry points. The shapes are fixed in the integration contract.

POST /api/v1/send is for mail the caller has already decided to send. identity-service uses it for magic links, invitations, and the staff notice. A company email rule does not suppress that call.

POST /api/v1/events is for catalog events. email-service queues one message for every enabled email rule on that company, service, and event. No matching rule returns 202 with skipped_reason: no_rule. Catalog default_enabled does not send mail.

Auth-lane events (identity.auth.magic_link.requested and identity.user.invited) have a built-in rule. It cannot be deleted, disabled, or pointed at other recipients. A sign-in link goes to the one address in the request. identity-service sends those two with /send and does not also post them to /events, so the person does not get a second copy.

identity.auth.magic_link.staff_blocked is Shellui's own copy in apps/email/builtin_auth.py. No rule, no company copy, not listed by GET /api/v1/catalog. /send only.

What a company configures​

A company stores one provider: Resend or SMTP. Credentials are encrypted at rest. API responses return a masked hint and configured.

Each email rule owns a copy of a library design. The library has 40 React Email designs in five sets: Barebone, Matte, Protocol, Arcane, and Studio. Suggested subjects and preheaders exist in English and French. A Shellui appearance theme can repaint a design's colors.

Newsletters are public lists with double opt-in. Broadcasts send one email to many people, each in their language.

Three lanes​

Auth, transactional, and bulk each have a worker. Sign-in mail uses the auth lane, so a broadcast does not delay it. See Lanes.

Configure and run​

Copy .env.example to .env, set SECRET_KEY, and run migrations. Docker Compose is the local path in Run email-service.

The container runs database migrations, then Gunicorn, one delivery worker per lane, and a Celery worker with beat. retry_webhooks and sweep_email_queue run every minute. purge_expired_data runs every hour at minute 17. Redis is required when DEBUG=false. With DEBUG=true and no Redis, the web app still starts and the scheduled jobs do not run.

Where to go next​

Pick the row that matches what you are doing:

You want toStart with
Run it locallyRun email-service
Run in the Shellui dev stackShellui dev stack
Set environment variablesConfiguration
Issue a service key and call the APIService keys and the integration contract
See which events existEvents catalog
Connect Resend or SMTPProviders
Turn an event into mailEmail rules
Edit copy, languages, and colorsTemplates and translations and the design library
Expose email settings to Shellui MCP agentsShellui MCP
Collect sign-ups from a websiteNewsletters
Mail many people at onceBroadcasts
See why sign-in mail has its own queueLanes
Call an HTTPS endpoint when mail changes stateWebhooks and n8n
Read past mail eventsEvent log
Lock down a production installSecurity
Scrape Prometheus or read admin countsMetrics
See retries and retentionScheduled jobs
Fix a send that did not go outTroubleshooting

Source and the changelog are on GitHub. These pages are built from docs/ by shellui/shellui and published on docs.shellui.com at docs.shellui.com/email.