Install KT8 Mail from the command line

Before you start

You'll need:

• Node.js 20 or later on your computer. Check with node --version.
• A Cloudflare account. It's free. Show me how.
• A domain on that account, such as yourname.co.uk. Show me how. Just trying it out? You can skip the domain and run KT8 Mail on your free workers.dev address first.
• R2 storage switched on. Open R2 in your Cloudflare dashboard once and switch it on. Cloudflare asks for a payment card, even for its free allowance, which is plenty for email.
• Cloudflare's Workers Paid plan ($5 a month) to send email to other people. Receiving works without it. Watch how (21 seconds).

No GitHub account is needed, and there's nothing to download or build.

Make an API token

The installer works through a Cloudflare API token that you make and can delete at any time.

1. Open API Tokens in your Cloudflare profile.
2. Choose Create Token, then Create Custom Token, and give it a name such as KT8 Mail installer.
3. Add these permissions:

4. Under Account Resources, pick your account. Under Zone Resources, pick all zones, or just the domain you'll use.
5. Choose Continue to summary, then Create Token, and copy it. Cloudflare shows it once, so keep it somewhere safe, such as your password manager.

API Tokens: Edit is optional. With it, KT8 Mail can add the people you invite to its sign-in list by itself. Without it, run the installer again after inviting someone.

Install

Open Terminal (or any command line) and run:

npx kt8-mail setup

It asks for your token (nothing shows as you paste it, which is normal), then a few questions:

1. Which domain to use, from the domains on your account. Or choose 0 to try it on your workers.dev address first.
2. The web address before your domain. It's mail unless you choose otherwise, so you'd open KT8 Mail at mail.yourname.co.uk.
3. The email address you'll sign in with. Cloudflare emails a sign-in code to it.

Then it shows each step as it happens:

Installing KT8 Mail 1.56 on Your Account for yourname.co.uk.

✓ Creating storage
✓ Installing KT8 Mail
✓ Switching on email for yourname.co.uk
✓ Setting up sign-in protection
✓ Switching on sending for yourname.co.uk

KT8 Mail is installed.
  Open it at https://mail.yourname.co.uk
  Sign in with you@yourname.co.uk: Cloudflare emails you a code.

If your domain already gets its email somewhere else, such as Google or Microsoft, the installer stops and asks before moving it. Nothing changes until you say yes.

If you'd rather not paste the token each time, set it first: export CLOUDFLARE_API_TOKEN=…. Please don't type it after the command itself, because your terminal would save it in its history.

What it sets up

Everything is created on your own Cloudflare account, and you can see it all in your Cloudflare dashboard:

• Storage: an R2 bucket called kt8-mail for your mail, attachments and backups.
• The app: a Worker called kt8-mail, at its own web address.
• Email: Email Routing for your domain, with a catch-all that sends every message to KT8 Mail.
• Email records: SPF, DKIM and DMARC, added to your DNS, so your mail is trusted.
• Sign-in protection: a Cloudflare Access app, so only you (and the people you invite) can open KT8 Mail.
• Sending: your domain switched on for Cloudflare's Email Sending.

It's safe to run more than once. Each step checks what's already there first, and your mail and settings are kept.

Updating

When there's a new version, KT8 Mail tells you in the app. To install it:

npx kt8-mail update

It finds your install, shows which version you have and which is new, and updates it. If you already have the latest version, it says so and stops. Add --force to run every step again anyway, for example after turning on the Workers Paid plan.

You can also update from the app or at kt8.com/install. All three do the same thing, so use whichever you like.

Options

Add these to skip the questions, for example in a script:

npx kt8-mail setup --domain yourname.co.uk --email you@yourname.co.uk

Run npx kt8-mail help to see them all, together with the token permissions.

If something goes wrong

The installer says what went wrong in plain English, with Cloudflare's own words underneath. Anything already done is kept, so after fixing the problem, run the same command again and it carries on.

• "Your API token is missing a permission": compare your token with the list above. You can edit a token in Cloudflare without making a new one.
• "Storage (R2) isn't switched on": open R2 in your Cloudflare dashboard and switch it on.
• "Sign-in protection uses Cloudflare Zero Trust": open Zero Trust in your Cloudflare dashboard once and choose the Free plan.
• "Sending to other people needs Cloudflare's Workers Paid plan": KT8 Mail is installed and receiving. Turn the plan on, then run npx kt8-mail update --force.

Still stuck? Ask in the Community or email hello@kt8.com.

Your token and your data

The installer runs on your computer and sends your token only to Cloudflare. Nothing is sent to KT8. It downloads KT8 Mail's own files from kt8.com, the same files every install uses. Once it's installed, KT8 Mail runs entirely on your Cloudflare account, and your mail never passes through us.

When you're done, you can delete the token in Cloudflare and make a new one the next time you update.