Run SendKettle on your own server
This guide puts SendKettle on one small rented server (a VPS), with HTTPS, a queue worker, the scheduler, Amazon SES for sending and nightly backups. You don't need to be a system administrator. You type the commands shown here, and an install script does the rest.
The examples use Hetzner Cloud. DigitalOcean works the same way; where it differs, the guide says so. Plan about an hour, plus waiting time for DNS and for Amazon to approve your SES account.
Screens at Hetzner, DigitalOcean and Amazon change now and then, so a button may have a slightly different name than in this guide. Look for the closest match.
Before you start
You need:
-
A domain name you control, for example
example.com, and a login at the company where its DNS is managed (often where you bought it). -
A subdomain for SendKettle, for example
news.example.com. The guide uses that name; type your own instead. -
Your copy of SendKettle on GitHub (or another git host). Note its address, for example
https://github.com/you/the_mailroom.git. -
A computer with a terminal: Terminal on macOS, PowerShell on Windows 10 or 11, or any Linux terminal.
-
An SSH key. If you don't have one, make it now on your computer:
ssh-keygen -t ed25519 -C "you@example.com"Press Enter to accept the file name, and type a passphrase you will remember. Then show the public half, which you will paste into Hetzner:
cat ~/.ssh/id_ed25519.pubIt is one line that starts with
ssh-ed25519. On Windows the command istype $env:USERPROFILE\.ssh\id_ed25519.pub.
Costs
Rough prices per month, without VAT, as of late 2026. Check the providers' price pages before you order.
| What | Rough cost per month | Notes |
|---|---|---|
| Hetzner Cloud CX22 (2 vCPU, 4 GB RAM, 40 GB disk) | 4 to 5 euro | Includes the public IPv4 address. |
| Hetzner server backups (optional) | about 1 euro | 20% of the server price. Daily snapshots of the whole server, on top of the backups in this guide. |
| Hetzner Storage Box BX11 (1 TB) | 3 to 4 euro | For the nightly backups. |
| Domain name | about 1 euro | Usually paid per year (10 to 15 euro). |
| Amazon SES | about 1 euro per 10,000 emails | 0.10 US dollar per 1,000 emails. |
| Postmark (instead of SES) | from about 15 euro | For 10,000 emails a month. |
| Anthropic API (optional) | usually under 1 euro | Pay per use for the AI assistant. |
| Uptime monitoring | 0 euro | The free plans of UptimeRobot or Better Stack are enough. |
| DigitalOcean (instead of Hetzner) | about 11 euro | A 2 GB droplet costs 12 US dollar. |
A typical total for a side project that sends 10,000 emails a month on Hetzner with SES is about 10 euro.
Step 1: Create the server
On Hetzner Cloud
- Sign up at Hetzner and open the Cloud Console. Create a Project, for example "SendKettle", and open it.
- Click Servers, then Add Server (sometimes Create Server).
- Location: pick one close to you or your subscribers, for example Falkenstein, Nuremberg or Helsinki.
- Image: choose Ubuntu 24.04.
- Type: choose Shared vCPU, x86 (Intel/AMD), then CX22. If CX22 is no longer listed, pick the smallest plan in the same row with at least 2 GB of RAM (Hetzner sometimes renames these, for example to CX23).
- Networking: leave both Public IPv4 and Public IPv6 on.
- SSH keys: click Add SSH key, paste the line that starts with
ssh-ed25519, give it a name and click Add SSH key. Make sure it is ticked. - Firewalls: click Create Firewall. Under Inbound rules, keep the rule for SSH (TCP, port 22), and add a rule for TCP port 80 and one for TCP port 443, both from Any IPv4 and Any IPv6. Name it "sendkettle", create it, and make sure it is selected for the new server.
- Backups: optional. Turning it on costs 20% extra and keeps 7 daily snapshots of the whole server.
- Name: for example
sendkettle. - Click Create & Buy now.
After a minute the server shows an IPv4 address such as 203.0.113.10 and an IPv6 network such as 2001:db8:1234:5678::/64. Write both down.
On DigitalOcean
- Click Create, then Droplets.
- Pick a Region, then under Choose an image pick Ubuntu 24.04 (LTS) x64.
- Under Choose Size: Basic, Regular, and the plan with 2 GB of memory. The 1 GB plan works too; the install script adds swap space so Composer has enough memory.
- Under Choose Authentication Method pick SSH Key, click New SSH Key, paste your key and add it.
- Tick Enable IPv6 if it is offered, and click Create Droplet.
- Open Networking, then Firewalls, and click Create Firewall. Keep SSH and add HTTP and HTTPS under Inbound Rules. Under Apply to Droplets, choose your droplet and create the firewall.
Step 2: Point a subdomain at the server
At the company that manages your domain's DNS, add these records. The names of the fields differ per company (Name or Host, Value or Points to, TTL).
| Type | Name | Value |
|---|---|---|
| A | news |
The IPv4 address, for example 203.0.113.10 |
| AAAA | news |
The IPv6 address of the server, for example 2001:db8:1234:5678::1 |
Hetzner shows a whole IPv6 network ending in ::/64. The server itself uses the first address in it: replace ::/64 with ::1. If you are unsure, leave the AAAA record out; IPv4 alone works.
Some DNS hosts want the full name (news.example.com) instead of news. If you can choose a TTL, pick 300 seconds or the lowest offered, so mistakes are quick to fix.
Check that the record works. On your computer, run:
nslookup news.example.com
The answer should show your server's address. It can take from a few minutes to a few hours before it does. You can start step 3 in the meantime; the script tells you when DNS is not ready yet.
Step 3: Run the install script
-
Log in to the server from your computer:
ssh root@203.0.113.10Type
yesthe first time, when asked whether you trust the server. -
Download the install script. Replace
you/the_mailroomwith your repository andmainwith your branch:curl -fsSLO https://raw.githubusercontent.com/you/the_mailroom/main/deploy/install.shIf your repository is private, that address doesn't work. Copy the file from your own computer instead, from inside your copy of the code:
scp deploy/install.sh root@203.0.113.10: -
Run it with your own values:
bash install.sh --domain news.example.com --email you@example.com --repo https://github.com/you/the_mailroom.git--domainis the subdomain from step 2.--emailis where Let's Encrypt sends a warning if your certificate ever fails to renew.--repois your repository. For a private repository, use its SSH address, such asgit@github.com:you/the_mailroom.git. The script then shows a key; add it on GitHub under your repository's Settings, Deploy keys, Add deploy key (leave Allow write access off) and press Enter.- Add
--branch nameif the code you want is not on the repository's default branch.
If you leave an option out, the script asks for it.
-
Wait about 5 to 10 minutes. The script prints each step. At the end it shows SendKettle is installed. and a list of next steps.
If the script stops, read the last lines: they say what went wrong. Fix it and run the same command again. Running it twice is safe; it checks what is already there and keeps your data.
If DNS was not ready, the script skips the certificate and says so. Wait until nslookup shows the right address and run the command again. HTTPS is required: you can't log in without it.
What the script sets up
| Part | Details |
|---|---|
| User | A deploy user that owns the code and runs the website, the queue worker and the scheduler. Your SSH key also works for it. |
| Software | PHP 8.4 (from the ondrej/php package source) with the extensions SendKettle needs, nginx, Composer, git, SQLite, supervisor, certbot, restic, ufw, fail2ban and automatic security updates. |
| Code | /var/www/sendkettle, installed with composer install --no-dev --optimize-autoloader. |
| Settings | .env with production values (see Settings in the .env file) and a new APP_KEY. |
| Database | SQLite at /var/www/sendkettle/database/database.sqlite, migrated. No demo data and no demo login. |
| Web server | nginx for your subdomain, with security headers, uploads up to 20 MB, dotfiles such as .env blocked and /.well-known/ open for the app. |
| HTTPS | A Let's Encrypt certificate that renews itself (certbot.timer). |
| Queue worker | The supervisor program sendkettle-worker, which sends the emails. It listens to the queues in priority order (--queue=system,journeys,webhooks,default,campaigns,imports), so a big campaign never delays journey emails, webhooks or system jobs. It restarts itself every hour and after a crash. |
| Scheduler | A cron entry in /etc/cron.d/sendkettle that runs schedule:run every minute, and the nightly backup. |
| Security | Firewall open only on ports 22, 80 and 443, fail2ban for SSH, passwords off for SSH (keys only), and daily security updates. |
Step 4: Create your first admin
The install never creates the demo login admin@example.com with the password password. Create your own account instead. If the script asked Create your admin account now? and you answered yes, you have done this already.
On the server, run:
sudo -u deploy php8.4 /var/www/sendkettle/artisan sendkettle:admin
It asks for:
- Email address: the address you log in with.
- Name: your name.
- Password (at least 12 characters), and then Type the password again. Nothing shows while you type; that is normal.
Then open https://news.example.com/login and log in. Your account is an Owner, the role that may do everything.
Next, protect the account with two-factor authentication: click your name, open Profile and set it up there. See Two-factor authentication and single sign-on.
The same command helps when you are locked out: run it with an existing email address, answer yes, and that account becomes an Owner with the new password.
If you once ran php artisan migrate --seed on this server, the demo account exists. Remove it under Team after you have logged in with your own account. The production checklist (step 7) warns you while it is there.
Step 5: Connect Amazon SES
SendKettle doesn't deliver email itself. It hands every email to a sending provider. Amazon SES is one of the cheapest. This step has several parts; do them in order.
Pick a region
- Sign in to the AWS console at
console.aws.amazon.com. Create an AWS account first if you don't have one. - At the top right, choose a region and keep it for every step below, for example Europe (Frankfurt) eu-central-1 or Europe (Ireland) eu-west-1.
- In the search bar at the top, type SES and open Amazon Simple Email Service.
Add your domain to SES
Use the domain of your from address, for example example.com for news@example.com. It doesn't have to be the subdomain of the server.
-
In the menu on the left, open Configuration, then Identities, and click Create identity.
-
Choose Domain and type
example.com. -
Under Advanced DKIM settings, keep Easy DKIM and RSA_2048_BIT. Leave Publish DNS records to Route53 off unless your DNS is at Amazon Route 53.
-
Click Create identity.
-
On the identity's page, open Authentication, then the DomainKeys Identified Mail (DKIM) section, and click Publish DNS records. You see three CNAME records like these:
Type Name Value CNAME abcdef123._domainkey.example.comabcdef123.dkim.amazonses.comCNAME ghijkl456._domainkey.example.comghijkl456.dkim.amazonses.comCNAME mnopqr789._domainkey.example.commnopqr789.dkim.amazonses.com -
Add all three at your DNS host. If your DNS host adds your domain to the name by itself, type only the part before
.example.com, such asabcdef123._domainkey.
SES checks the records by itself. After a while (minutes, sometimes hours) the identity shows Verified.
Add SPF and DMARC
Add these two TXT records at your DNS host as well:
| Type | Name | Value |
|---|---|---|
| TXT | example.com (often written as @) |
v=spf1 include:amazonses.com ~all |
| TXT | _dmarc.example.com (or _dmarc) |
v=DMARC1; p=none; rua=mailto:dmarc@example.com |
- A domain may have only one SPF record. If
example.comalready has a TXT record that starts withv=spf1(for example for your normal email), don't add a second one. Addinclude:amazonses.comto the existing one, before the~allat the end:v=spf1 include:_spf.google.com include:amazonses.com ~all. - The DMARC record asks inbox providers to send reports to
dmarc@example.com. Use an address that exists.p=noneonly collects reports; you can tighten it later, see Domains. - Optional: in SES, under the identity's Custom MAIL FROM domain, click Edit and set
bounce.example.com. SES then shows one MX and one TXT record to add. Bounces then come from your own domain, which helps with DMARC.
Leave the SES sandbox
A new SES account is in the "sandbox": it may only send to addresses you have verified, and at most 200 emails a day. Ask Amazon to lift that:
- In the SES menu, open Account dashboard (or Get set up) and click Request production access.
- Mail type: Marketing.
- Website URL: your website, or
https://news.example.com. - Use case description: explain in a few sentences how people join your list and how you handle bounces. For example: "I send a monthly newsletter to people who signed up on my website with double opt-in. Every email has a one-click unsubscribe link. Bounces and complaints are processed automatically through an SNS webhook and those addresses are removed from the list."
- Tick the box to agree to the terms and click Submit request.
Amazon usually answers within a day. While you wait, verify your own address so you can test: Identities, Create identity, Email address, and click the link in the email Amazon sends.
Create SMTP credentials
SendKettle talks to SES over SMTP. You need SMTP credentials; an AWS access key for the SES API does not work here.
- In the SES menu, open SMTP settings. Note the SMTP endpoint, for example
email-smtp.eu-central-1.amazonaws.com. - Click Create SMTP credentials. Keep the suggested user name and click Create user.
- Click Show user SMTP security credentials (or Download .csv file) and copy the SMTP user name and SMTP password. The password is shown only once.
Enter the details in SendKettle
- In SendKettle, click Settings, then Email sending. You are on the Sending and company page.
- In the Sending provider box, set Provider to Amazon SES (set your region in the host).
- SMTP host: the SMTP endpoint from SES, for example
email-smtp.eu-central-1.amazonaws.com. The preset uses eu-west-1; change it if your region is different. - Port:
587. Encryption: STARTTLS (port 587). On DigitalOcean, which blocks port 587 on new accounts, use port2587with the same encryption. - Username: the SMTP user name. Password / API key: the SMTP password.
- Default from email: an address on your verified domain, such as
news@example.com. Default from name: your name or your company's. - Max emails per minute: SES shows your sending rate per second on the Account dashboard. Multiply it by 60 and use a bit less, for example
600for 14 per second. Use60while you are still in the sandbox. - Fill in Company or sender name, Postal address and Time zone. The law requires your name and postal address in marketing email.
- Click Save settings.
- In the Send a test email box, type an address (in the sandbox: one you verified in SES) and click Send test email. If it fails, the message shows the error from SES.
More about these fields: Sending and deliverability.
Check the domain in SendKettle
SendKettle checks your SPF, DKIM and DMARC records too, and the production checklist needs this to pass.
- In Settings, scroll to Authenticate your domain and click Open domains.
- In the Sending domains box, type
example.comin Domain and click Add domain. - On the domain's page, in the Record settings box:
- DKIM selector: the first part of one of the three SES names, before
._domainkey, for exampleabcdef123. - SPF include:
amazonses.com. - DKIM value: the value of that same record, for example
abcdef123.dkim.amazonses.com.
- DKIM selector: the first part of one of the three SES names, before
- Click Save record settings, then Check DNS records.
When SPF, DKIM and DMARC all show Passed, the domain shows Verified. If one fails, the page says what it found and how to fix it. DNS changes can take a while; check again later. The Domains guide has more detail.
Send bounces and complaints back
When an address bounces or someone marks your email as spam, SES can tell SendKettle, so that address gets no more email. This keeps your SES account in good standing.
- In SendKettle, open Settings and find the Bounce & complaint webhooks box. Click the address next to Ses and copy it. It looks like
https://news.example.com/webhooks/ses/followed by a long secret code. Treat it like a password. - In the AWS console, in the same region, search for SNS and open Simple Notification Service.
- Open Topics and click Create topic. Choose Standard, name it
sendkettle-feedbackand click Create topic. - On the topic's page click Create subscription. Protocol: HTTPS. Endpoint: paste the address from step 1. Leave Enable raw message delivery off. Click Create subscription. Its status is Pending confirmation.
- Copy the topic's ARN from the top of the topic page (it starts with
arn:aws:sns:). In SendKettle, open Settings, paste it under Amazon SES, SNS topic ARNs and click Save. Do this before AWS sends its confirmation, because SendKettle only accepts messages from topics on this list. AWS then sends a signed confirmation request. SendKettle checks the signature and confirms the subscription by itself. Refresh the subscription in AWS: the status changes to Confirmed. If it stays on Pending confirmation, check the ARN in Settings and click Request confirmation on the subscription. - Back in SES, open Identities, click
example.comand open the Notifications tab. Under Feedback notifications click Edit. - Set Bounce feedback and Complaint feedback to the topic
sendkettle-feedback. Click Save changes.
To test it, send a test email from Settings to bounce@simulator.amazonses.com (or complaint@simulator.amazonses.com). A minute later, the System status page under Help shows Bounce webhooks: Last one from Ses.
Postmark instead of SES
Postmark costs more but has a simpler setup and a well-known delivery record.
- In Postmark, create a Server, and use its Default Broadcast Stream for newsletters. Postmark keeps marketing email apart from transactional email and expects it on a broadcast stream.
- In Sender Signatures add your domain, and add the DKIM and Return-Path records Postmark shows at your DNS host.
- In the broadcast stream's setup instructions, create SMTP credentials for that stream (labels may differ).
- In SendKettle, choose Provider: Postmark, and fill in the username and password from step 3.
- In the Postmark stream, add a webhook to the Postmark address from Bounce & complaint webhooks, with Bounce and Spam complaint turned on.
- Under Domains, add your domain with the DKIM selector Postmark shows and the SPF include
spf.mtasv.net.
Platform sending (cloud edition)
This is only for the hosted (cloud) edition. In the super admin panel you can let an account send through the platform's own Amazon SES account instead of its own keys (see Super admin panel). The platform's keys are only in the .env file. They are never stored in the database, so no settings page, export or API answer can contain them.
Set it up once in AWS, in the region you send from:
- Get the SES account out of the sandbox for that region and verify the platform's own domain, as in the steps above.
- In SNS, create a Standard topic, for example
sendkettle-platform-events. Copy its ARN. - On the topic, click Create subscription. Protocol: HTTPS. Endpoint:
https://news.example.com/webhooks/platform-ses(yourAPP_URL). SendKettle confirms the subscription by itself oncePLATFORM_SES_TOPIC_ARNis set. - Edit the topic's Access policy so that only SES in your own AWS account may publish to it: allow
sns:Publishfor the serviceses.amazonaws.comwith the conditionaws:SourceAccountset to your account id. - In IAM, create a user (or role) for SendKettle with only these SES permissions:
ses:SendEmail,ses:SendRawEmail,ses:CreateConfigurationSet,ses:CreateConfigurationSetEventDestination,ses:CreateEmailIdentity,ses:DeleteEmailIdentity,ses:GetAccount. Create an access key for it. - Optional, but recommended: in CloudWatch, create two alarms on the SES metrics
Reputation.BounceRate(for example above 0.04) andReputation.ComplaintRate(for example above 0.0008), with the topic from step 2 as the action when the alarm goes off. Also allowsns:Publishforcloudwatch.amazonaws.comin the topic's access policy. SendKettle then hears about a reputation problem within minutes; without the alarms it notices at the hourly check of the SES account status.
Then add these to .env and rebuild the cached settings:
| Setting | Value |
|---|---|
PLATFORM_SES_KEY |
The access key ID from step 5. |
PLATFORM_SES_SECRET |
The secret access key from step 5. |
PLATFORM_SES_REGION |
The SES region, for example eu-west-1. |
PLATFORM_SES_TOPIC_ARN |
The ARN from step 2. |
PLATFORM_SES_PREFIX |
Optional, default sendkettle. Goes in front of every configuration set name, such as sendkettle-account-12. Use another one per installation when several share one SES account. |
What happens then:
- When you switch an account to platform sending, SendKettle creates the configuration set for that account and points its bounce, complaint, delivery and delay events at the topic.
- Each sending domain of the account is added to SES with a DKIM key SendKettle made. The customer adds one DKIM TXT record (selector
sk1), plus SPF withinclude:amazonses.comand DMARC, as shown on the domain's page. - Every email names the account's configuration set and carries the workspace as a message tag. An event is only applied when the workspace in its tag belongs to the account of its configuration set. Messages that are not signed by SNS, come from another topic, are older than an hour or were seen before are refused.
- A reputation alarm on the topic, or an SES account status other than healthy at the hourly check, pauses the accounts that send through the platform with the highest bounce or complaint rates and emails the super admins. See Automatic suspension.
Built-in sending (cloud edition)
With Built in, customers' email goes out through this server's own MAIL_ settings, for example Postfix on the server itself (MAIL_URL=smtp://127.0.0.1:25?auto_tls=false). Customers always send from their own verified domain, so SendKettle signs that email itself with a DKIM key it made per sending domain (Symfony's DKIM signer, relaxed/relaxed, rsa-sha256). The customer publishes the public key at sk1._domainkey.<their domain>; the private key is stored encrypted with APP_KEY. Only email from a domain that is verified in the sending workspace is signed, and only with that workspace's key.
As the platform owner:
-
Keep OpenDKIM signing the platform's own domain (for example
sendkettle.com) as it does now. SendKettle never signs the platform's domains, so password resets, invitations and other platform email keep relying on OpenDKIM. Make sure OpenDKIM only signs its own domains (itsSigningTable, for example*@sendkettle.com sendkettle), so customer email isn't signed twice. A second signature is harmless if it happens: SendKettle's signature covers neitherReceivednorDKIM-Signatureheaders, so the one OpenDKIM adds on top leaves it valid, and DMARC passes on the customer's aligned signature. It only adds bytes and an unalignedd=of the platform to every customer email. -
Publish the SPF host customers include, with the server's public address:
_spf.sendkettle.com. TXT "v=spf1 ip4:<server IPv4> -all"Add
ip6:<server IPv6>too when the server sends over IPv6. -
Set
SENDKETTLE_SPF_INCLUDE=_spf.sendkettle.comin.envand rebuild the cached settings. The domain page then asks customers forinclude:_spf.sendkettle.comand the check requires it. Without it, the SPF check falls back to the SPF include saved for the domain, if any. -
Check that the server's address has a matching reverse DNS (PTR) name, as for any mail server.
The envelope sender (Return-Path) of customers' built-in email is a signed bounce address on the via domain, one per recipient, such as bounce+12-<signature>@send.sendkettle.com (see the next section). SPF is then checked for the via domain and passes there, so the SPF include on customers' own domains is optional; DKIM alone gives DMARC alignment. Set SENDKETTLE_PLATFORM_RETURN_PATH=false to keep the customer's own from address as envelope sender, as before.
Built-in DKIM is on in the cloud edition and off on self-hosted servers. SENDKETTLE_BUILTIN_DKIM=true or false overrides that. Raw MIME relayed through the transactional SMTP relay is passed on as it is, without a signature.
Sending via the platform address (cloud edition)
A workspace whose from domain is not connected still sends at once: from a fixed address of its own on the via domain, such as duranet@send.sendkettle.com, named "Duranet via SendKettle", with Reply-To set to the customer's own address. SendKettle signs that email in the app with the platform's own DKIM key for the via domain, so OpenDKIM needs no change. Customers can't choose the address; it is made once per workspace from its company name. See Domains.
| Setting | Default | What it does |
|---|---|---|
SENDKETTLE_VIA |
true |
false turns sending via the platform address off: customers then have to connect their own domain first (the strict rule from before). |
SENDKETTLE_VIA_DOMAIN |
send. + the APP_URL host |
The via domain. Keep it a subdomain used only for this. |
SENDKETTLE_VIA_DKIM_SELECTOR |
sk1 |
The DKIM selector of the platform's key. |
SENDKETTLE_PLATFORM_RETURN_PATH |
true |
Puts the envelope sender of all customers' built-in email on the via domain, so bounces come back to the app. |
As the platform owner, once:
-
Print the records. The first run makes the platform's 2048-bit DKIM key and stores it encrypted (with
APP_KEY) as a platform setting:sudo -u www-data php artisan sendkettle:via-domain --ip=<server IPv4> -
Publish these records for the via domain (here
send.sendkettle.com):send.sendkettle.com. TXT "v=spf1 ip4:<server IPv4> -all" sk1._domainkey.send.sendkettle.com. TXT "v=DKIM1; k=rsa; p=<the key the command prints>" _dmarc.send.sendkettle.com. TXT "v=DMARC1; p=quarantine; adkim=r; aspf=r" send.sendkettle.com. MX 10 <this server's mail host name>Add
ip6:<server IPv6>to the SPF record when the server sends over IPv6. You can addrua=mailto:...to the DMARC record with a mailbox you read. -
Let Postfix accept all mail for the via domain and hand it to SendKettle. One pipe handles everything: bounces and complaints are applied to the right workspace, and replies sent to a workspace's via address are forwarded to that workspace's reply-to address. The script does all of this, only where it isn't done yet, with a backup of every file it changes (
<file>.bak-<date-time>):sudo VIA_DOMAIN=send.sendkettle.com APP_DIR=/var/www/sendkettle APP_USER=www-data PHP_BIN=/usr/bin/php \ bash /var/www/sendkettle/scripts/postfix-via-domain.shSet
APP_DIR,APP_USER(the user that owns the app and can write itsstorage) andPHP_BINto your server's values. By hand, the result is:# /etc/postfix/main.cf (keep what is already in relay_domains and transport_maps) relay_domains = $mydestination, send.sendkettle.com transport_maps = hash:/etc/postfix/transport recipient_delimiter = + # /etc/postfix/transport send.sendkettle.com sendkettle-via: # /etc/postfix/master.cf sendkettle-via unix - n n - 10 pipe flags=Rq user=www-data argv=/usr/bin/php /var/www/sendkettle/artisan sendkettle:via-mail --sender=${sender} -- ${original_recipient}Then
sudo postmap /etc/postfix/transport,sudo postfix checkandsudo systemctl reload postfix. Servers set up earlier with thesendkettle-bouncepipe keep working:sendkettle:bounceis the old name of the same command, and it reads the sender from theReturn-Pathheader Postfix adds. Switching tosendkettle-via(run the script) passes the sender explicitly.What the pipe does with each message:
bounce+<workspace>-<signature>@: a bounce or complaint. The signature covers the workspace and the one recipient that email went to, so a report only counts for that recipient. Bounce addresses in the older format (signed for the workspace only) are ignored.<workspace address>@(such asduranet@, also with+anything): a reply to the via address itself. It is forwarded fromno-reply@send.sendkettle.comto the workspace's Reply-to email under Settings, Sender defaults (else its default from address), with the original sender as Reply-To, signed with the platform's via DKIM key. It also shows in the workspace's shared inbox. It is never sent to any other address.- Anything else, such as an unknown name or
no-reply@: dropped without an answer, so a forged sender never gets a bounce (no backscatter).
Replies are not forwarded for a paused or closed account, above
SENDKETTLE_VIA_REPLIES_PER_HOUR(default 100) per workspace, aboveSENDKETTLE_VIA_REPLY_MAX_BYTES(default 10 MB), twice for the same Message-ID, when they come from the via domain or were forwarded before, when they are an auto-reply from the workspace's own reply-to address, more than one auto-reply an hour from the same sender, or bulk or list mail sent from this platform. Each message is logged with its workspace and what happened (Via reply forwarded,Via reply dropped (rate limit)and so on), without addresses. -
Keep the via domain out of OpenDKIM's
SigningTable: the app signs that mail, forwarded replies included. The script comments out lines for the via domain (with a backup) and warns about a wildcard such as*@*.sendkettle.comthat would also match it.sendkettle.comitself stays in theSigningTable. -
Accounts on platform sending (Amazon SES): add the via domain as a verified identity in the same SES region, with Easy DKIM. Their via email then goes through the account's configuration set, and bounces come back through SNS as before.
-
Open the production checklist: Via domain DKIM record passes once the DKIM record is published.
Raw MIME (the send-raw API and the transactional SMTP relay) can't be rewritten, so it still needs a from address on a connected domain and is refused otherwise.
Optional: SENDKETTLE_DOMAIN_CONNECT=true shows Connect automatically on a domain's page when the customer's DNS host supports Domain Connect and knows SendKettle's template. It stays off until that template is accepted; see Domain Connect.
Step 6: Turn on the AI assistant (optional)
The AI assistant writes subject lines, rewrites text and drafts emails with Claude. It stays off until you add an Anthropic API key. Anthropic bills you directly for what you use.
- Sign in at
console.anthropic.com, add a payment method or credits, open API keys and click Create Key. Copy the key; it starts withsk-ant-. - In SendKettle, open Settings and click the AI section.
- Paste the key in API key, pick a Model and click Save AI settings.
See AI assistant for what it can do.
In the cloud edition you set ANTHROPIC_API_KEY in .env instead; paid customers then use the assistant without a key of their own. See Services the platform provides.
Step 7: Open the production checklist
In SendKettle, open Settings, click the Account section and then Production checklist (Admins and Owners only). You also find it at the bottom of Help, System status.
It checks:
| Check | Passes when |
|---|---|
| Edition | SENDKETTLE_EDITION is selfhosted or cloud |
| Debug mode is off | APP_DEBUG=false |
| Running in production mode | APP_ENV=production |
| Public address uses HTTPS | APP_URL starts with https:// and matches the address in your browser |
| Sending provider | A provider is saved under Settings and it is not Log only |
| Sending domain verified | At least one domain under Domains shows Verified |
| Scheduler | It ran in the last 5 minutes |
| Queue worker | No job has waited longer than 10 minutes |
| No demo password | No Owner or Admin has the password password, and admin@example.com doesn't exist |
| Backups | backup.sh finished in the last 26 hours |
| Storage is writable | The app can write to storage, bootstrap/cache and the database |
| Login cookie stays on the app's address | SESSION_DOMAIN is empty, and over HTTPS the login cookie has the __Host- prefix |
Each item that needs work has a How to fix link to the right part of this guide. Right after the install, Backups fails until you set them up, and Sending provider and Sending domain verified fail until step 5 is done.
Settings in the .env file
The script writes these values in /var/www/sendkettle/.env:
| Setting | Value | Why |
|---|---|---|
APP_ENV |
production |
Turns off developer tools and asks for confirmation before risky commands. |
APP_DEBUG |
false |
With true, error pages show code and secrets to anyone. |
APP_URL |
https://news.example.com |
Every link in your emails is built from it. |
SENDKETTLE_EDITION |
selfhosted |
The edition. Keep selfhosted on your own server. cloud is for the hosted service and turns on its extra parts, such as public signup and the public home page: visitors who are not logged in see the public site on / (features, pricing, questions, business contact and the waiting list, see Public site), and a few guides under /docs. Any other value runs as selfhosted, and the production checklist shows it as a problem. |
SENDKETTLE_PLATFORM_DOMAINS |
sendkettle.io,mail.sendkettle.io |
Cloud only. The platform's own domains, comma separated. Customers can't send from them or use them (or their subdomains) for tracking links and pages. Empty means the host of APP_URL and the domain of MAIL_FROM_ADDRESS. See Domains. |
LOG_LEVEL |
warning |
Logs problems, not every detail. |
LOG_STACK |
daily |
A new log file every day, kept for 14 days (LOG_DAILY_DAYS). |
SESSION_SECURE_COOKIE |
true |
The login cookie is only sent over HTTPS. |
SESSION_DOMAIN |
empty | The login cookie belongs to the app's own address only. Never set it to the parent domain (.example.com): the cookie would then also go to every customer website on a subdomain. The production checklist fails when it is set. |
SESSION_COOKIE |
not set | Over HTTPS the login cookie is called __Host-sendkettle_session and the form token cookie __Host-XSRF-TOKEN. Browsers only accept a __Host- cookie from the app's own address, so a script on a customer website can't plant one. Leave it out of .env; the first visit after an update signs everyone in again once. |
QUEUE_CONNECTION |
database |
Emails wait in the database until the queue worker sends them. |
QUEUE_LANES |
true |
Puts campaign sends, journeys, webhooks, imports and system jobs on their own queues. Without it every job uses the one default queue, as on installs from before this setting. |
DB_CONNECTION, DB_DATABASE |
sqlite, the full path |
The database file. |
APP_KEY |
generated once | Encrypts stored passwords and signs links. Never change it, and keep a copy (the backups include it). |
Optional: MAIL_FAIR_SHARE_PER_MINUTE (default 1000) is the most campaign emails a minute one workspace sends once there is more than one workspace, even when its own Max emails per minute is 0 or higher. Every workspace's emails then get their turn in the queue instead of waiting behind someone else's 100,000. Set it near what your worker sends in a minute; 0 turns it off. With one workspace it does nothing.
Optional, cloud: SENDKETTLE_SPF_INCLUDE (for example _spf.sendkettle.com) is the SPF host customers include for built-in sending, and SENDKETTLE_BUILTIN_DKIM turns signing built-in email with each customer's DKIM key on or off (default: on in the cloud edition). See Built-in sending.
Optional: MAIL_ALLOW_PRIVATE_SMTP_HOSTS=true lets workspaces send through a mail server on a private network or a non-mail port, such as a relay on this server. Leave it off when people you don't fully trust are Admin of a workspace: they could point the SMTP host at internal services.
Optional, cloud: the keys of the services the platform provides to paid customers: ANTHROPIC_API_KEY (AI writing), PLATFORM_AI_MODEL, OPENAI_API_KEY (pictures made by AI), DEEPL_API_KEY and DEEPL_API_FREE (translating forms), GIPHY_API_KEY (GIF search), EMAILONACID_API_KEY and EMAILONACID_ACCOUNT_PASSWORD (inbox previews), RECAPTCHA_SITE_KEY, RECAPTCHA_SECRET_KEY, HCAPTCHA_SITE_KEY and HCAPTCHA_SECRET_KEY (bot check on forms) and PLATFORM_CAPTCHA (the bot check on the platform's own forms). GEOIP_DATABASE_PATH is the GeoLite2 file for opens by country, SAFE_BROWSING_API_KEY the Google Safe Browsing key for campaign screening; the web push keys are made by the app. A self-hosted server ignores the service keys. See Services the platform provides.
To change a setting, edit the file and rebuild the cached settings:
sudo -u deploy nano /var/www/sendkettle/.env
sudo -u deploy php8.4 /var/www/sendkettle/artisan config:cache
supervisorctl restart sendkettle-worker:*
Running the install script again sets the values in the table back, except APP_KEY.
Search engines
The install script sets nginx up for fast pages: versioned stylesheets and scripts are cached for a year, text is compressed, and /robots.txt comes from the app. On a server installed before this, add those settings by hand. Search engines lists them, with the redirect from www and the steps for Google Search Console.
Websites on subdomains (cloud edition)
Customer websites live on their own subdomain of a separate websites domain, such as corner-bakery.sites.sendkettle.com. They never run on the app's own address: their pages contain the customer's own HTML and scripts. Below, sites.sendkettle.com is the websites domain and sendkettle.com the app; use your own names.
DNS records
At the DNS host of the domain (Hetzner DNS, for example), add:
| Type | Name | Value |
|---|---|---|
| A | *.sites.sendkettle.com |
the server's IPv4 address |
| A | sites.sendkettle.com |
the server's IPv4 address |
| AAAA | *.sites.sendkettle.com |
the server's IPv6 address, only if the app is reachable over IPv6 |
| AAAA | sites.sendkettle.com |
the same IPv6 address, only if you added the one above |
The wildcard does not cover sites.sendkettle.com itself, hence the second record. That bare name redirects to the public home page.
Wildcard certificate
A certificate for *.sites.sendkettle.com needs the DNS challenge of Let's Encrypt: Let's Encrypt checks a TXT record instead of a web request. With Ploi and Hetzner DNS:
- In the Hetzner DNS console, create an API token (API tokens) and copy it.
- In Ploi, add that token as a Hetzner DNS provider for DNS verification of certificates.
- In Ploi, request a Let's Encrypt certificate for
sites.sendkettle.comand*.sites.sendkettle.comwith DNS verification. Ploi adds the TXT records through the token, gets the certificate and renews it by itself.
Use the Ploi site that will serve the websites domain (next step). Keep the token private: it can change every record of the DNS zone.
nginx
Requests for the websites domain go to the same app, from the same folder, as sendkettle.com. Either add the names to the app's site in Ploi, or add a site for sites.sendkettle.com with the same project folder and this server block. Copy root, the PHP socket and the fastcgi lines from the app's own server block, so both are the same:
server {
listen 80;
listen [::]:80;
server_name sites.sendkettle.com *.sites.sendkettle.com;
return 301 https://$host$request_uri;
}
server {
listen 443 ssl;
listen [::]:443 ssl;
http2 on;
server_name sites.sendkettle.com *.sites.sendkettle.com;
ssl_certificate /etc/nginx/ssl/sites.sendkettle.com/server.crt;
ssl_certificate_key /etc/nginx/ssl/sites.sendkettle.com/server.key;
root /home/ploi/sendkettle.com/public;
index index.php;
location / {
try_files $uri $uri/ /index.php?$query_string;
}
location ~ \.php$ {
include fastcgi_params;
fastcgi_pass unix:/var/run/php/php8.4-fpm.sock;
fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
}
}
Use the certificate paths Ploi shows for the certificate. Run nginx -t and reload nginx. Don't add the websites domain to TRUSTED_HOSTS: the app accepts its names on its own once SITES_DOMAIN is set.
Settings
In .env:
SITES_DOMAIN=sites.sendkettle.com
# Optional: free accounts get a name like site-4821 (default), or choose one themselves.
SENDKETTLE_FREE_SITE_NAMES=generated
# Optional: more brand names to refuse as website addresses, comma separated.
SITES_BLOCKED_NAMES=
Leave SESSION_DOMAIN empty and SESSION_COOKIE unset (see Settings in the .env file). Then run php artisan migrate --force and php artisan config:cache, and restart the queue worker.
Check it
curl -I https://sites.sendkettle.com/answers301to the public home page.curl -I https://nothing-here.sites.sendkettle.com/answers404withX-Robots-Tag: noindex, nofollow.curl -I https://nothing-here.sites.sendkettle.com/loginanswers404as well: the app itself never answers on the websites domain.- Publish a test website and open it at its address under the websites domain.
- The production checklist shows Login cookie stays on the app's address as passed.
Updates
To install a new version of your repository, log in to the server and run:
bash /var/www/sendkettle/deploy/update.sh
It copies the database, shows a "back soon" page, pulls the new code with git pull, runs composer install, migrates the database, rebuilds the caches, restarts the queue worker and PHP, and opens the site again. If nothing is new, it says Already up to date and stops.
If an update fails, the site stays on the "back soon" page and the script prints the commands to go back to the version you had. The copy of the database is in /var/www/sendkettle/database/backups/ (the newest five are kept).
To stay on tagged releases instead of every change on the branch, run update.sh --to latest or --to v1.2.0. Versions and upgrading explains version numbers, the release notes, skipping versions and going back.
Queue lanes on an older install
Servers installed before queue lanes existed keep working: their worker listens to the default queue and every job still goes there. To get the lanes, run the install script again (it writes QUEUE_LANES=true and the new worker command), or do it by hand:
- Add
QUEUE_LANES=trueto/var/www/sendkettle/.env. - In
/etc/supervisor/conf.d/sendkettle-worker.conf, change the command toqueue:work database --queue=system,journeys,webhooks,default,campaigns,imports --sleep=3 --max-time=3600. - Run
sudo -u deploy php8.4 /var/www/sendkettle/artisan config:cache, thensupervisorctl reread && supervisorctl update.
Change the worker and the setting together: with lanes on and the old worker, nothing on the named queues is picked up.
The server installs security updates for Ubuntu and PHP by itself every night. Restart it now and then for kernel updates: reboot (the app starts again on its own).
Backups
Everything that matters lives in three places: the SQLite database, the .env file (because of APP_KEY) and uploaded files in storage/. deploy/backup.sh copies all three every night at 03:17 with restic, encrypted, to a place outside the server. The database is copied with SQLite's own .backup command, so the copy is consistent even while emails are going out.
Until you finish this section, the production checklist shows Backups as failed.
Set up a Storage Box
A Hetzner Storage Box is cheap storage that restic can reach over SFTP.
-
In the Hetzner console, open Storage Boxes and order a BX11 in a location other than your server's, if offered.
-
Open the Storage Box. Under Settings, turn on SSH support (and External reachability if your server is not at Hetzner). Note the Username (like
u123456) and Server (likeu123456.your-storagebox.de). Set a password if you are asked to. -
On your server, make an SSH key for root if it doesn't have one, and copy it to the Storage Box. Replace
u123456with your username; it asks for the Storage Box password once:[ -f /root/.ssh/id_ed25519 ] || ssh-keygen -t ed25519 -N "" -f /root/.ssh/id_ed25519 cat /root/.ssh/id_ed25519.pub | ssh -p 23 u123456@u123456.your-storagebox.de install-ssh-key -
Give the Storage Box a short name for SSH:
cat >> /root/.ssh/config <<'EOF' Host storagebox HostName u123456.your-storagebox.de User u123456 Port 23 IdentityFile /root/.ssh/id_ed25519 EOF ssh storagebox lsThe last command should list the Storage Box's folders without asking for a password.
Or use S3
Any S3 service works: Amazon S3, Hetzner Object Storage, Backblaze B2 or Cloudflare R2. Create a private bucket and an access key that may read and write only that bucket. In the next part, use the S3 lines in backup.env instead of the Storage Box line:
RESTIC_REPOSITORY=s3:https://s3.eu-central-1.amazonaws.com/your-bucket/sendkettle
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
For Hetzner Object Storage the address looks like s3:https://fsn1.your-objectstorage.com/your-bucket/sendkettle.
Turn on the backups
-
Copy the settings file and create a password for the backups:
cp /var/www/sendkettle/deploy/backup.env.example /etc/sendkettle/backup.env chmod 600 /etc/sendkettle/backup.env openssl rand -base64 32 > /etc/sendkettle/restic-password chmod 600 /etc/sendkettle/restic-password cat /etc/sendkettle/restic-password -
Store the password that the last command shows in your password manager. Without it, nobody can read the backups, including you.
-
Open the settings with
nano /etc/sendkettle/backup.env. For a Storage Box, leaveRESTIC_REPOSITORY=sftp:storagebox:sendkettleas it is. For S3, replace it with the S3 lines from above. Save with Ctrl+O, Enter, and close with Ctrl+X. -
Optional: if you use a check-in monitor such as Healthchecks.io, put its ping address in
PING_URL=. You get an email when a night's backup doesn't arrive. -
Create the backup store and make the first backup:
bash /var/www/sendkettle/deploy/backup.sh init bash /var/www/sendkettle/deploy/backup.sh
The last line should say Backup finished. From now on cron runs it every night; the output goes to /var/log/sendkettle-backup.log. Restic keeps 7 daily, 4 weekly and 6 monthly backups (change KEEP_DAILY, KEEP_WEEKLY and KEEP_MONTHLY in backup.env) and checks the backup store every Sunday.
Test a restore
A backup you have never restored is only a hope. Test it now, and again every few months:
bash /var/www/sendkettle/deploy/backup.sh restore-test
It restores the newest backup into a temporary folder, checks the database, counts the users, checks that .env has an APP_KEY, and removes the folder again. It ends with Restore test passed and the date of the backup. bash /var/www/sendkettle/deploy/backup.sh snapshots lists all backups.
Restore a backup
If the server is lost, create a new one (steps 1 to 3, with the same domain), then:
-
Set up the Storage Box or S3 access again (the SSH key part of Set up a Storage Box, or the S3 lines), put the same restic password in
/etc/sendkettle/restic-password, and copybackup.envas described above. -
Restore into a separate folder and put the files in place:
bash /var/www/sendkettle/deploy/backup.sh restore /root/restore supervisorctl stop sendkettle-worker:* cd /var/www/sendkettle rm -f database/database.sqlite-wal database/database.sqlite-shm cp /root/restore/var/backups/sendkettle/database.sqlite database/database.sqlite cp /root/restore/var/backups/sendkettle/env .env cp -a /root/restore/var/www/sendkettle/storage/app/. storage/app/ chown -R deploy:deploy database .env storage chmod 600 .env bash deploy/update.sh --no-pull supervisorctl start sendkettle-worker:* -
If the new server uses a different domain, run the install script again with the new
--domain. It updatesAPP_URLand keeps the restoredAPP_KEY.
Keep a copy somewhere else
A Storage Box at the same company as your server protects you against a broken server, not against losing your Hetzner account. Once a month, take a copy home as well:
bash /var/www/sendkettle/deploy/backup.sh export
It writes one .tar.gz file and shows the scp command to run on your own computer to download it. The file contains .env with your APP_KEY, so keep it somewhere private, and delete it from the server afterwards with rm /var/backups/sendkettle/sendkettle-export-*.tar.gz.
Another option is a second backup store at another company: copy /etc/sendkettle/backup.env to a second file with an S3 address and run SENDKETTLE_BACKUP_CONFIG=/etc/sendkettle/backup-s3.env bash /var/www/sendkettle/deploy/backup.sh from a second cron line.
Monitoring
- System status: in SendKettle, open Help and then System status. It shows whether the database, the sending provider, the queue worker, the scheduler, deliveries, bounce webhooks and image storage work. See Knowledge base and support.
- Production checklist: Settings, Account, Production checklist (step 7).
- Uptime: sign up for a free uptime monitor such as UptimeRobot or Better Stack, and add an HTTP(S) monitor for
https://news.example.com/up. That page answers with status 200 while the app runs. You get an email or a text when it stops answering. - Backups: the optional
PING_URLinbackup.envwarns you when a nightly backup is missing.
Troubleshooting
Log in to the server first: ssh root@203.0.113.10.
The queue is not running
Signs: campaigns stay on Sending, test campaigns don't arrive, System status says jobs are waiting.
-
Check the worker:
supervisorctl status sendkettle-worker:*It should say RUNNING. If not, start it with
supervisorctl start sendkettle-worker:*. -
If it keeps stopping, read its log:
tail -n 50 /var/www/sendkettle/storage/logs/worker.log. -
Jobs that failed are listed with
sudo -u deploy php8.4 /var/www/sendkettle/artisan queue:failed. After fixing the cause, retry them withsudo -u deploy php8.4 /var/www/sendkettle/artisan queue:retry all.
The scheduler is not running
Signs: scheduled campaigns stay Scheduled, automations don't move on, the checklist shows Scheduler failed.
-
Check that the cron file exists:
cat /etc/cron.d/sendkettle. If it is missing, run the install script again. -
Run the scheduler once by hand and read the output:
cd /var/www/sendkettle && sudo -u deploy php8.4 artisan schedule:run -
Check that cron itself runs:
systemctl status cron.
Emails are stuck
- Check the queue worker first (above).
- Open Settings and use Send test email. The message shows the error from your provider, for example a wrong password or a from address that SES has not verified.
- Still in the SES sandbox? Then only verified addresses receive email. See Leave the SES sandbox.
- The SMTP port must be reachable from the server:
nc -zv email-smtp.eu-central-1.amazonaws.com 587should say succeeded. Hosting companies often block outgoing mail ports on new accounts. DigitalOcean blocks 25, 465 and 587; Hetzner blocks 25 and 465. SES also listens on port 2587: set Port to2587with STARTTLS (port 587) in Settings and test again. Or ask the hosting company's support to unblock the port. - Check Max emails per minute in Settings: a low value makes a big campaign take hours. With several workspaces,
MAIL_FAIR_SHARE_PER_MINUTEalso caps each one. - A campaign that says Preparing the recipient list for more than a few minutes is picked up again by the scheduler (it must run, see above). After three failed tries it is paused with a notice; press Resume sending once the cause (often the queue worker) is fixed.
500 errors and where the logs are
A "Server error" page means something went wrong inside the app. The details are in the logs:
| Log | Where |
|---|---|
| SendKettle | /var/www/sendkettle/storage/logs/laravel-YYYY-MM-DD.log (one per day) |
| Queue worker | /var/www/sendkettle/storage/logs/worker.log |
| nginx | /var/log/nginx/sendkettle.error.log |
| PHP | /var/log/php8.4-fpm.log |
| Backups | /var/log/sendkettle-backup.log |
Show the last lines of today's app log:
tail -n 50 /var/www/sendkettle/storage/logs/laravel-$(date +%F).log
Don't turn on APP_DEBUG on a live server to see errors; read the log instead. After changing .env, always run config:cache (see Settings in the .env file). A "502 Bad Gateway" means PHP is not running: systemctl restart php8.4-fpm.
Permission errors
Signs: "Permission denied" or "failed to open stream" in the log, uploads that fail, or Storage is writable failing in the checklist. This usually happens after running a command as root inside /var/www/sendkettle. Always run artisan and composer as deploy (sudo -u deploy ...), as in this guide.
To repair the permissions:
chown -R deploy:deploy /var/www/sendkettle
chmod -R u+rwX,g+rwX,o-rwx /var/www/sendkettle/storage /var/www/sendkettle/bootstrap/cache /var/www/sendkettle/database
chmod o+x /var/www/sendkettle/storage /var/www/sendkettle/storage/app
chmod -R o+rX /var/www/sendkettle/storage/app/public
chmod 600 /var/www/sendkettle/.env
Running the install script again does the same.
SQLite or MySQL
The install uses SQLite: the whole database is one file, there is no database server to look after, and a backup is one copy of that file. For one server and a list of tens of thousands of contacts, that is plenty. The script turns on SQLite's WAL mode, so the website, the queue worker and the scheduler can work at the same time, and runs one queue worker.
Consider MySQL or PostgreSQL only when you want several app servers or several queue workers sending at full speed. SendKettle supports them through the normal Laravel DB_* settings, but this guide and its scripts (including backup.sh) are written for SQLite. See Installation.