Sending and deliverability

SendKettle hands every email to a mail server that delivers it: the built-in route of your SendKettle, or a sending provider of your own. This guide explains the built-in route, how to connect a provider, how to set up your domain so your emails reach the inbox, and how to let SendKettle know about bounces and spam complaints.

Only Admins and Owners can open Settings.

The boxes on the Settings page

Settings has a separate box for each part, each with its own save button:

Box What is in it Button
Sending provider Built in, or your own provider with its server and login Save sending provider
Sender defaults Default from email, Default from name, Default reply-to email Save sender defaults
Company details Name, postal address, phone, website, abuse reports email Save company details
Send rate and time zone Max emails per minute, Time zone Save

Saving one box never changes the others. You can fill in your company details without choosing a provider, and they never ask for SMTP settings.

Built in: nothing to set up

When your SendKettle can deliver email on its own, the Provider list starts with Built in (nothing to set up). On a new workspace it is already selected.

  • On a server you run yourself, email goes out through the mail settings of the server (the MAIL_ settings in .env, such as the server's own mail server).
  • In SendKettle Cloud, email goes out through the platform's mail server, or through the platform's sending service when the platform switched your account to it (see below). You don't need an account at a provider.

In the cloud nothing else is needed: until your own domain is connected, email goes out as "Your name via SendKettle" from your SendKettle address, with replies to you (see Domains). On your own server, verify your from address or its domain under Domains.

Choosing Built in and saving removes the provider, server, port, encryption, username and password that were saved before. With Built in, test emails, invitations and password resets come from the server's own address.

Built in is not in the list when the server only writes email to a log file (MAIL_MAILER=log or array). Then connect a provider as described below.

Built in: DKIM and SPF for your own domain

In SendKettle Cloud, email sent Built in goes out through the platform's mail server, from your own domain once it is connected. So that inboxes trust it, SendKettle signs it with a DKIM key it made for your domain:

  • When you add a sending domain under Domains, SendKettle makes a key pair for it. You publish the public key as a TXT record with the name sk1._domainkey.yourdomain and the value v=DKIM1; k=rsa; p=.... The domain's page shows the exact value. The private key stays on the server and is never shown.
  • SPF is optional: bounces come back to SendKettle's own address, so SPF passes there. If you like, add include:_spf.sendkettle.com (the domain's page shows the name for your installation) to the SPF record of your domain.
  • DMARC: add a DMARC record as for any provider. DKIM alone already lines up with your from address, which is what DMARC needs; SPF is extra.
  • Emails are only signed once the domain is verified: click Check DNS records until DKIM and DMARC pass. Emails from a domain that isn't verified in the same workspace are never signed with its key.
  • Bounces: the envelope sender (Return-Path) of these emails is your own from address, so bounce messages that are not handled by the platform end up in that mailbox. That is also the address SPF is checked for.

Email through a provider of your own is not changed: your provider signs it with its own key. On a server you run yourself this is off unless the owner turns it on with SENDKETTLE_BUILTIN_DKIM=true.

Connect a provider

  1. Click your name at the bottom of the menu, then Settings.
  2. In the Sending provider box, choose your provider under Provider. For a known provider, SMTP host, Port and Encryption are filled in, and Username shows a hint of what to enter.
  3. Fill in Username and Password / API key from your provider's dashboard.
  4. Type your Current password and click Save sending provider.
  5. In Send a test email, enter an address and click Send test email. The message says which mailer was used, or says that sending failed (the details are in the server log).

The SMTP host must be the public address of your provider, and Port one of 25, 465, 587 or 2525. Addresses on private or internal networks (such as 127.0.0.1 or 10.0.0.5) are refused, also when a host name only later starts pointing there. When sending fails, the message stays general and the provider's exact answer goes to the server log. To use a mail relay on your own server, the server administrator sets MAIL_ALLOW_PRIVATE_SMTP_HOSTS=true in the .env file.

The password is stored encrypted. When you edit the settings later, leave Password / API key empty to keep the saved one.

Changing the provider, host, port, encryption, username or password needs your own Current password, and so does switching to or from Built in. The first workspace's server also sends password reset and invitation emails, so only an Owner can change it there, and the other Owners get an email about the change through the old server. Admins can still save the other boxes, and the sending server of other workspaces.

Provider presets

Provider SMTP host Port Username Password / API key
Custom SMTP server Your server 587 Your SMTP username Your SMTP password
Mailgun smtp.mailgun.org 587 The SMTP login of your domain, such as postmaster@your-domain Its SMTP password
Postmark smtp.postmarkapp.com 587 Your Server API token The same Server API token
Amazon SES email-smtp.eu-west-1.amazonaws.com 587 Your SES SMTP username (this is not your AWS access key) Your SES SMTP password
SendGrid smtp.sendgrid.net 587 apikey Your SendGrid API key
Brevo smtp-relay.brevo.com 587 Your Brevo SMTP login Your Brevo SMTP key
Resend smtp.resend.com 587 resend Your Resend API key

The Amazon SES preset uses the eu-west-1 (Ireland) region. If your SES account is in another region, change the region part of SMTP host, for example email-smtp.us-east-1.amazonaws.com.

Log only (development, nothing is sent) writes every email to the server's log file. Use it for testing. The SMTP fields are hidden for it.

HTTP APIs

Amazon SES, Postmark and Mailgun can also be reached through their HTTP API instead of SMTP. Pick Amazon SES (HTTP API), Postmark (HTTP API) or Mailgun (HTTP API) under Provider. There is no host, port or encryption to fill in: SendKettle always calls the provider's own address over HTTPS. An API call is quicker than an SMTP conversation, so large campaigns go out faster.

Provider Username Password / API key Extra field
Amazon SES (HTTP API) The access key ID of an IAM user that may call ses:SendEmail and ses:SendRawEmail Its secret access key AWS region, for example eu-west-1
Postmark (HTTP API) (not needed) Your Server API token Message stream: broadcast for campaigns, or the ID of another stream
Mailgun (HTTP API) Your sending domain, for example mg.example.com Your Mailgun API key Region: us or eu, where your Mailgun account lives

SPF, DKIM and the bounce webhooks are the same as for the SMTP presets. With SMTP, a queue worker keeps its connection to the server open between emails as long as the settings stay the same, so existing SMTP setups also send faster than before.

Encryption

  • STARTTLS (port 587) works with all presets. Use it unless your provider says otherwise.
  • SSL/TLS (port 465) for servers that only accept encrypted connections on port 465.
  • None (not recommended) sends your password and emails unencrypted.

Default from email and name

Campaigns use their own From name and From email. With a provider of your own, the defaults in Sender defaults are used for the test email in Settings, team invitations, password reset emails, and API messages without a sender. Default reply-to email is optional: replies to a campaign go there when neither the campaign nor its audience has a reply-to address.

Sending through the platform (cloud)

In SendKettle Cloud, the platform can send your email through its own sending service. Then the Sending provider box only says so: you don't set up a provider or keys, and bounces and complaints are handled for you. The platform decides this for your account; you can't switch it yourself.

Until your domain is connected, email goes out from your SendKettle address. To send from your own domain, add it under Domains and press Check DNS records: the domain's page then shows the DKIM record the platform made for it. Add it, together with SPF and DMARC, at your DNS host. See Domains.

Rate limit

Max emails per minute limits how fast campaign and automation emails leave the queue. Use the limit of your provider's plan, or a lower one while you warm up a new domain. 0 means no limit. Test emails and API messages are not limited. When you send a campaign, its emails are spread out over the minutes ahead by this limit, so a big send never holds up other work on the server (or other workspaces).

Company details

Company or sender name and Postal address are required. Anti-spam laws such as CAN-SPAM and GDPR require your name and postal address in marketing emails. SendKettle adds them to the footer of every campaign and automation email. Once email really goes out (through Built in or a provider), campaigns and automation emails are not sent without a postal address: the Postal address item on the checklist is red, and a send that is already going out pauses until you fill it in.

Time zone

Pick your Time zone in the Send rate and time zone box. SendKettle uses it for Send at times, RSS send hours, birthday emails, send-time optimisation and every date on screen. Times are stored in UTC, so changing the time zone later doesn't move anything that is already scheduled.

What every email includes

You don't need to do anything for these:

  • an HTML version and a plain text version,
  • the one-click unsubscribe header that Gmail and Yahoo require for bulk senders, so readers can unsubscribe from the inbox itself,
  • a footer with your company name and address, an Unsubscribe link and a View in browser link,
  • tracking for opens and clicks.

Authenticate your domain: SPF, DKIM and DMARC

Gmail, Yahoo and other inbox providers reject or spam-folder bulk email from domains that are not authenticated. You set this up with DNS records on the domain of your from address. Your provider's dashboard gives you the exact values. The Domains screen shows the records your domain needs and checks them for you.

Record What it does What it looks like
SPF Lists the servers allowed to send email for your domain. A TXT record on your domain, such as v=spf1 include:<provider> ~all. You can only have one SPF record, so add your provider to the existing one if there is one.
DKIM Adds a digital signature to your emails, so inboxes can check they were not changed. One or more CNAME or TXT records your provider generates, with names such as s1._domainkey.
DMARC Tells inboxes what to do with emails that fail SPF and DKIM, and where to send reports. A TXT record on _dmarc, such as v=DMARC1; p=none; rua=mailto:you@yourdomain.

Steps:

  1. In your provider's dashboard, add your sending domain. It shows the SPF and DKIM records.
  2. Add the records in the DNS settings of your domain, at your domain registrar or DNS host.
  3. Add a DMARC record. Start with p=none, which only monitors.
  4. Wait until your provider shows the domain as verified. This can take from minutes to a day. Add the domain on the Domains screen and click Check DNS records to see which records pass.
  5. Use an address on that domain as the from email of your audiences and campaigns.

Bounce and complaint webhooks

When an email bounces or a reader marks it as spam, your provider can tell SendKettle through a webhook: a message sent from the provider's server to a web address on yours. SendKettle then:

  • marks the address Cleaned after a hard bounce,
  • counts soft bounces and marks the address Cleaned after the third one,
  • unsubscribes the address after a spam complaint,
  • sets the soft bounce count back to zero when a later email is delivered or opened, so occasional full mailboxes don't add up to a cleaned address.

Hard bounces and spam complaints also put the address on the suppression list, so no signup form, API call or forward can make SendKettle email it again.

This applies to the address in every audience it is on. Every campaign and automation email carries its own Message-ID and an X-SendKettle-Id header with the same value (and, for Mailgun, Postmark, SendGrid and Brevo, the provider's own metadata header), which providers send back in their webhooks. The bounce, complaint or delivery is then shown in the report of the exact email it belongs to. Only when an event carries no such id is it shown with the campaign the contact last received.

The Bounce & complaint webhooks box in Settings lists one web address per provider: Postmark, Mailgun, Amazon SES, SendGrid, Resend, Brevo and Generic. Each contains a secret code. Treat it like a password and don't share it.

The address alone is not enough. Every request must also carry your provider's own signature or credentials, and SendKettle checks them with keys you add under Webhook signature keys, before it changes any contact. A provider without keys shows Keys missing: requests are refused, and its webhooks are refused until you add them. Secret keys are stored encrypted and never shown again; leave a field blank to keep the saved key.

  1. Click the address for your provider in Settings to select it, and copy it.
  2. In your provider's dashboard, find the webhook settings.
  3. Add a webhook with that address and turn on the events listed below.
  4. Copy the signing key (or choose the credentials) as described for your provider below, paste it under Webhook signature keys and click Save webhook keys. The provider's badge changes to Signature check on.

Which events each provider should send

Provider Events to turn on How SendKettle reads them
Postmark Bounce, Spam complaint, Delivery Hard bounce, bad email address and manually deactivated count as hard bounces. Other bounce types are soft.
Mailgun Permanent failure, Temporary failure, Spam complaints, Delivered messages Permanent failures are hard bounces, temporary failures are soft.
Amazon SES Bounces, complaints and deliveries, through an SNS topic with an HTTPS subscription to the address Permanent bounces are hard, other bounces soft.
SendGrid Bounced, Dropped, Deferred, Spam reports, Delivered Bounces and drops are hard, blocked bounces and deferrals are soft.
Resend email.bounced, email.complained, email.delivered Every bounce counts as hard.
Brevo Hard bounce, Soft bounce, Invalid email, Blocked, Spam / complaint, Delivered Hard bounces, invalid and blocked addresses are hard, soft bounces are soft.

Signature checks per provider

Each provider proves that a webhook comes from them in its own way. Requests with a missing or wrong signature are refused with an error and change nothing. A request that was already handled (a replay, or the provider retrying) is answered with OK but not applied a second time.

Amazon SES

SES sends bounces and complaints through Amazon SNS, and SNS signs every message with a certificate from AWS.

  1. In the AWS console, create an SNS topic for bounces and complaints (or one for each), and point SES's bounce and complaint notifications at it.
  2. Copy the topic's ARN, for example arn:aws:sns:eu-west-1:123456789012:ses-bounces, and paste it under SNS topic ARNs. Put each topic on its own line.
  3. Save, then create an HTTPS subscription on the topic with the Amazon SES address from Settings.

SendKettle only accepts messages from the topics you listed. It checks the SNS signature (signature version 1 and 2) with the certificate SNS names, and only downloads that certificate over https from sns.<region>.amazonaws.com, in the topic's own region. Messages more than an hour old are refused. The subscription confirmation that AWS sends is confirmed automatically, but only after its signature checks out.

Mailgun

  1. In Mailgun, open Sending, Webhooks and copy the HTTP webhook signing key.
  2. Paste it under HTTP webhook signing key in Settings.

Mailgun signs a timestamp and a one-time token with this key (HMAC-SHA256). Requests older than 5 minutes are refused, and so is a token that was used before.

Postmark

Postmark doesn't sign its webhooks. It can send a user name and password (basic auth) and custom headers instead, which you choose.

  1. Make up a user name and a long random password (at least 16 characters). Under Postmark in Settings, enter them as Basic auth user name and Basic auth password.
  2. In Postmark, open the server, Webhooks, and add the webhook. Turn on Basic auth credentials and enter the same user name and password.
  3. Instead of basic auth, or as well, you can add a Custom header in Postmark, for example X-Webhook-Token with a long random value, and enter the same name and value under Custom header name and Custom header value.

When you set up both, every request needs both. Postmark sends no signed timestamp, so the same request sent again within a day is recognised and not applied twice.

SendGrid

  1. In SendGrid, open Settings, Mail Settings, Event Webhook, and turn on Signed Event Webhook Requests.
  2. Copy the Verification Key that appears and paste it under Verification key (public key) in Settings.

SendGrid signs the timestamp and body of every request with an ECDSA key; SendKettle checks the signature with the verification key. Requests more than 5 minutes old are refused.

Resend

  1. In Resend, open Webhooks, open your webhook and copy the Signing secret. It starts with whsec_.
  2. Paste it under Resend, Signing secret in Settings.

Resend signs every request (through Svix) with this secret, over the message id, a timestamp and the body. Requests more than 5 minutes old, and message ids seen before, are refused.

Brevo

Brevo can send a bearer token or a user name and password with each webhook.

  1. Make up a long random token (at least 16 characters) and enter it under Brevo, Bearer token.
  2. Add the webhook in Brevo with token authentication and the same token, so Brevo sends Authorization: Bearer <token>. Through Brevo's API, set auth to {"type": "bearer", "token": "<token>"} when you create the webhook.

Or use basic auth: enter a user name and password under Basic auth user name and Basic auth password, and add them to the webhook in Brevo. One of the two must match. Like Postmark, Brevo sends no signed timestamp, so the same request sent again within a day is not applied twice.

The generic format

Other services, or your own code, can use the Generic address. Send a POST request with a JSON body like this:

{"type": "hard_bounce", "email": "ann@example.com"}

type can be bounce, hard_bounce or hard for a hard bounce, soft_bounce or soft for a soft bounce, complaint or spam for a complaint, and delivered or delivery for a delivered email. Add "message_id" with the email's Message-ID (or its X-SendKettle-Id header) to apply the event to that exact email.

Sign every request the same way SendKettle signs its own outgoing webhooks. Choose a signing secret of at least 32 characters and enter it under Generic, Signing secret. Then send the header X-SendKettle-Signature: t=<timestamp>,v1=<signature>, where the timestamp is the current Unix time in seconds and the signature is the hex HMAC-SHA256 of <timestamp>.<body> with the secret. Requests more than 5 minutes old, and a repeat of the same request, are refused.

New webhook addresses

If you think a webhook address has leaked, or someone who could see it has left, click Create new webhook URLs in the box. The old addresses stop working at once, for every provider, and the box shows the new ones. Paste the new address into each provider you use. Only Admins can do this, and it is recorded in the audit log.

To remove the keys of a provider, tick it under Remove all keys of and save. Its webhooks are then refused.

Bounces without webhooks

When the receiving server refuses an address outright while SendKettle is sending (an SMTP error from 550 to 554 about the recipient or mailbox), the address is treated as a hard bounce, with or without webhooks.

Common problems

"Sending failed: ..." after Send test email

The provider refused the connection or the login. Check the host, port, encryption, username and password. Some providers need you to verify the from address or domain first.

The test works but campaigns don't arrive

Campaigns go through the queue. Ask the person who runs your server to check that the queue worker is running. See the installation guide.

Emails land in spam

Check SPF, DKIM and DMARC for the domain of your from email. Use a from address on a domain you verified with your provider, and avoid the subject line habits the checklist warns about.

"The mail host field format is invalid."

Type only the host name, such as smtp.example.com, without https:// or a port.

My saved password stopped working after a server move

The password is encrypted with the server's application key. If that key changed, type the password again and save.