RecapitoOne inbox for every mailbox you already have.

• Credentials encrypted at rest with AES-256-GCM

  IMAP passwords, SMTP passwords and provider API keys are encrypted before they reach the database, with a fresh random 96-bit IV per value and a version-prefixed envelope so the scheme can be rotated later. Authenticated encryption means tampered ciphertext fails at decrypt time instead of being replayed at a mail server. Login passwords are different — those are bcrypt-hashed and never decryptable, which is correct for a credential the server only ever verifies.

• Mandatory secrets, with no insecure fallback

  JWT_SECRET and ENCRYPTION_KEY have no default, no fallback and no development shortcut. The API validates both at startup and refuses to boot if either is missing, too weak, or set to a well-known placeholder such as changeme. An application that boots successfully while signing tokens with a guessable secret looks healthy and is completely compromised; failing to start is the safer outcome.

• Registration closed by default, first account becomes admin

  A self-hosted instance is reachable by anyone who finds the URL, so public sign-up is off unless you set ALLOW_REGISTRATION=true. The very first account is always allowed — otherwise a fresh deployment could never be bootstrapped — and it is granted administrator rights. Everyone after that is created deliberately.

• Attachments are always downloads, never rendered inline

  An email attachment is untrusted content from an arbitrary sender. Every one is served as application/octet-stream with an attachment disposition, X-Content-Type-Options: nosniff and a restrictive Content-Security-Policy, so a malicious .html or .svg can never execute on the application's origin with your session. The on-disk filename is a random UUID; the sender's filename is a database column, sanitised back into a header at download time.

• HTML email renders inside a sandboxed iframe

  An HTML message body is arbitrary markup written by whoever sent it. Rather than injecting it into the page, Recapito renders it in an iframe with neither allow-scripts nor allow-same-origin, so the browser refuses to run script in it at all and gives it an opaque origin — a browser-enforced boundary rather than a sanitiser that has to keep pace with new bypasses. A Content-Security-Policy inside that frame blocks remote script outright and allows only data: images, which has the pleasant side effect of stopping tracking pixels quietly reporting that you opened the mail.

The project is equally explicit about the gaps: message bodies are stored unencrypted so that server-side search works, there is no built-in rate limiting on the auth endpoints, and there is no audit log. All of it — plus key-rotation consequences and a deployment hardening checklist — is written up in SECURITY.md.

1. Clone the repository

   git clone https://github.com/iampopye/recapito.git
   cd recapito

   Copy

2. Create your environment file

   cp .env.example .env

   Copy

3. Generate the secrets

   # Signs session tokens
   echo "JWT_SECRET=$(openssl rand -hex 32)"
   
   # Encrypts stored IMAP and SMTP credentials — back this up
   echo "ENCRYPTION_KEY=$(openssl rand -hex 32)"
   
   # Postgres password — no default is baked into the code
   echo "DATABASE_PASSWORD=$(openssl rand -base64 32)"

   Copy

   Paste each line into .env. ENCRYPTION_KEY must be exactly 64 hex characters — a 32-byte key. Store it somewhere separate from your database backups: an archive holding both is, functionally, a backup of your plaintext mailbox passwords.

4. Bring the stack up

   cd docker
   docker compose --env-file ../.env up -d

   Copy

   The Compose files live in docker/, so --env-file is what points them at the .env in the repository root. Migrations run on API startup — there is no separate migration step.

Open http://localhost:3000 and create the first account, which becomes the administrator. Add a mailbox with its IMAP host, port and credentials; the daemon picks it up and starts syncing. To send, configure Mailgun under Settings, or add a Brevo or SMTP provider under SMTP Providers. DEPLOYMENT.md covers putting it on a real server, with nginx and Let's Encrypt.

flowchart LR
    User([Browser])

    subgraph self["Recapito — self-hosted"]
        FE["Frontend<br/>Next.js 14 · :3000"]
        API["API<br/>NestJS 10 · :3001/api"]
        DAEMON["imap-daemon<br/>Node · imapflow"]
        DB[("PostgreSQL 16")]
    end

    IMAP["Your IMAP providers<br/>Gmail · Fastmail · Zoho · any IMAP host"]
    SEND["Send providers<br/>Mailgun · Brevo · SMTP"]

    User --> FE
    FE -->|REST over HTTP| API
    API --> DB
    API -->|send mail| SEND
    SEND -.->|delivery webhooks| API
    DAEMON -->|IMAP IDLE + fetch| IMAP
    DAEMON -->|write threads and messages| DB

New-mail detection works on a rolling 30-minute IMAP SINCE window, fetched in batches of 50, de-duplicated on the RFC message ID. A message is never stored twice, and a brief daemon outage is caught up automatically on reconnect.

• OAuth2 / XOAUTH2 for Gmail and Outlook Top priority

  Mailboxes authenticate with a stored username and password today. Google turned off plain password sign-in for IMAP in 2024, so a Gmail account now needs an app password and a Workspace admin can switch even that off. Token-based authentication is the single change that most widens what Recapito can connect to.

• Rich-text compose

  Compose is a plain textarea. A proper editor — formatting, links, inline quoting — is not built.

• Filters and rules

  No automatic categorisation. Labels and folders are applied by hand.

• Email forwarding

  You can reply and compose. Forwarding an existing message is not implemented.

• Saved searches

  Search runs, but there is no way to pin a query and come back to it.

• Internationalisation

  The interface is English-only, with no translation layer to plug other languages into.

• Sending attachments

  Attachments on received mail are stored, listed and downloadable. Attaching a file to an outgoing reply is not implemented — compose is text only.

• Test coverage

  Five spec files cover encryption, authentication and user management. The frontend and the daemon have none at all — the most useful unglamorous contribution available.

Everyone taking part is expected to follow the Code of Conduct. Found a security problem? Report it privately through GitHub security advisories rather than in a public issue.