JavaScript Disabled This app requires JavaScript to function. Please enable it in your browser settings. Refresh Page

Connection Lost

Attempting to reconnect

Back to Overview

Email Setup: SMTP and Provider APIs

Configure outgoing email through SMTP or a provider's API. Tymeslot needs it for booking confirmations, password resets and meeting reminders.

Luka Breitig

Updated 2 September 2026

Before You Begin

A running Tymeslot instance with access to its environment variables or .env file
SMTP credentials from your email provider (host, port, username and password), or an API key from a supported provider
A verified sending domain, or at minimum a sending address your provider permits
The ability to restart Tymeslot after changing environment variables

By the end of this guide, Tymeslot sends booking confirmations, password reset emails and meeting reminders through your mail provider.

Why Email Configuration Is Required

Tymeslot sends every automated notification by email, so you must configure it. Without email, your instance appears to work, but attendees never receive confirmations and hosts never learn that a booking arrived.

Tymeslot sends email for:

Booking confirmation to attendee: sent as soon as someone books a slot
Booking notification to host: tells you when someone books a new meeting
Cancellation and rescheduling notices: sent to both host and attendee
Meeting reminders: sent at a time you choose before each meeting
Password reset: without it, users cannot recover their account
Email verification: the link that confirms a new account's address
Integration alerts: a warning when a calendar or video connection needs reconnecting

1 Set the Core Environment Variables

Open your .env file (or your hosting platform's environment variable settings) and add the following. SMTP_PORT defaults to 587 if you leave it out, and a relay that authorises by network rather than by login takes neither SMTP_USERNAME nor SMTP_PASSWORD.

These apply to every SMTP provider; the provider sections below change only the SMTP_* values.

EMAIL_ADAPTER=smtp
EMAIL_FROM_NAME="Acme Corp"
EMAIL_FROM_ADDRESS=noreply@acme.com

SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USERNAME=user@example.com
SMTP_PASSWORD=secret

Environment variable reference

Variable	Purpose
EMAIL_ADAPTER	Must be `smtp` (the default) for SMTP. To send through a provider's API instead, use `postmark`, `sendgrid`, `mailgun` or `ahasend` (see below).
EMAIL_FROM_NAME	The display name recipients see in their inbox, such as "Acme Corp"
EMAIL_FROM_ADDRESS	The sender address recipients see. It must be on a domain your SMTP server lets you send from.
SMTP_PORT	`587` (the default) for STARTTLS, which is recommended. `465` for implicit TLS. Avoid `25`, which most cloud providers block.
SMTP_SSL	Optional. `true` forces implicit TLS on a port other than 465, such as 2465 or 8465.

2 Choose Your Provider

Replace the SMTP_* values from Step 1 with the values for your provider. All other variables remain the same.

Gmail

Google blocks regular Gmail passwords for SMTP connections. Generate an App Password instead: a 16-character password that grants SMTP access without exposing your main account password.

To create an App Password:

Go to myaccount.google.com/security and confirm that 2-Step Verification is enabled. App Passwords are only available when 2-Step Verification is on.
On the same Security page, search for or scroll to App passwords and open it. You may be prompted to sign in again.
In the App name field, type "Tymeslot" and click Create.
Google displays a 16-character password. Copy it now, because Google shows it only once, and use it as SMTP_PASSWORD.

The new App Password now appears in your account's list of app passwords, and Tymeslot can send through Gmail.

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your.address@gmail.com
SMTP_PASSWORD=xxxx xxxx xxxx xxxx

If you get "535 Username and Password not accepted" or "534 Application-specific password required"

You are using your regular Google account password, which Gmail rejects for SMTP. Generate an App Password with the steps above; it is the only credential Gmail accepts here.

Gmail is for Low-Volume Deployments

Free Gmail accounts can send about 500 emails per day, and Google Workspace accounts about 2,000. If your instance takes bookings every day, use a transactional service such as SendGrid or Amazon SES.

SendGrid

SendGrid uses an API key as the SMTP password. The username is not your account email but always the literal string apikey.

To get your API key:

In the SendGrid dashboard, go to [Settings] → [API Keys].
Click Create API Key, give it a name like "Tymeslot", and select Restricted Access.
Under Mail Send, set access to Full Access. No other permissions are needed.
Click Create & View and copy the key. It starts with SG. and is shown only once.

SendGrid then returns you to the API Keys list, where the new key appears under the name you chose. You must also verify your sending domain under [Settings] → [Sender Authentication] before SendGrid delivers any email.

SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USERNAME=apikey
SMTP_PASSWORD=SG.your_api_key_here

Amazon SES

SES SMTP credentials are a separate set generated for SMTP only. Do not use your AWS access key and secret here.

To generate SES SMTP credentials:

In the AWS console, go to [Amazon SES] → [SMTP Settings].
Click Create SMTP Credentials. AWS creates a dedicated IAM user for them.
Download the credentials file. The SMTP Username (starts with AKIA) and SMTP Password go into your environment.
In [Verified Identities], verify the domain or email address that matches your EMAIL_FROM_ADDRESS. SES will not send from an unverified identity.

Once the identity status shows Verified, SES is ready to send. The SMTP endpoint hostname depends on your region: use the one shown on the SMTP Settings page.

SMTP_HOST=email-smtp.eu-west-1.amazonaws.com
SMTP_PORT=587
SMTP_USERNAME=AKIAIOSFODNN7EXAMPLE
SMTP_PASSWORD=your_ses_smtp_password

SES Sandbox Mode

New SES accounts start in sandbox mode, where you can only send to verified email addresses, such as your own test addresses. To send to any recipient, request production access through [Account Dashboard] → [Request Production Access]. AWS usually responds within one business day.

Generic SMTP (Mailgun, Brevo, Fastmail, and others)

Any provider that offers standard SMTP works with Tymeslot. Find the SMTP credentials in your provider's dashboard or documentation: you need the hostname, port, username and password.

SMTP_HOST=smtp.your-provider.com
SMTP_PORT=587
SMTP_USERNAME=your_smtp_username
SMTP_PASSWORD=your_smtp_password

Port 465 vs 587

Set SMTP_PORT=465 only when your provider requires implicit TLS; Tymeslot switches to it automatically on that port. Port 587 uses STARTTLS and is the preferred modern standard; any other port uses TLS only if the relay offers it. If your provider serves implicit TLS on another port (2465 or 8465, for example), add SMTP_SSL=true; without it the connection waits for a greeting the relay never sends.

Your own mail server (Stalwart, Mailcow, Mailu, Postfix)

You configure a self-hosted relay like any other, with one difference: Tymeslot verifies the server's certificate against the system trust store, and a mail server you run yourself typically serves a self-signed certificate until you point it at Let's Encrypt. Some deployments also expose only 465 for submission and leave 587 closed, so 465 may be your only option. A relay that accepts mail from your network without a login, such as a local Postfix, needs no SMTP_USERNAME or SMTP_PASSWORD: leave both unset.

To fix a certificate error, trust the authority that issued the certificate, which keeps the connection authenticated. Mount the CA's PEM bundle into the container and point SMTP_CACERTFILE at it:

SMTP_HOST=mail.yourdomain.com
SMTP_PORT=465
SMTP_USERNAME=noreply@yourdomain.com
SMTP_PASSWORD=your_mailbox_password
SMTP_CACERTFILE=/app/data/smtp-ca.pem

Disabling Verification Is a Last Resort

Where there is no CA to trust, SMTP_TLS_VERIFY=none accepts any certificate the relay presents. Mail is still encrypted, but Tymeslot no longer checks that it is talking to your mail server, so an intercepted connection cannot be detected. Use it to confirm a setup works, then move to SMTP_CACERTFILE or a publicly trusted certificate.

🔀 Alternative: Send Through a Provider's API

Some providers can be used through their HTTP API instead of SMTP. The emails are identical; only the transport differs. Use the API when your host blocks outbound SMTP ports, or when you want delivery failures reported as readable errors rather than numeric SMTP codes. Set EMAIL_ADAPTER to the provider name and give it the credentials below instead of the SMTP_* variables.

Postmark

EMAIL_ADAPTER=postmark
POSTMARK_API_KEY=your_server_api_token

SendGrid

Create the key under Settings → API Keys. Only the "Mail Send" permission is used.

EMAIL_ADAPTER=sendgrid
SENDGRID_API_KEY=SG.your_api_key

Mailgun

MAILGUN_DOMAIN is the sending domain you verified with Mailgun. EU-hosted accounts must also set MAILGUN_BASE_URL or Tymeslot sends to the US endpoint, which rejects an EU key.

EMAIL_ADAPTER=mailgun
MAILGUN_API_KEY=your_api_key
MAILGUN_DOMAIN=mg.yourdomain.com
# EU accounts only
MAILGUN_BASE_URL=https://api.eu.mailgun.net/v3

AhaSend

Both values come from the AhaSend dashboard: the API key from Credentials, and the account ID from the account the key belongs to.

EMAIL_ADAPTER=ahasend
AHASEND_API_KEY=aha-sk-your_api_key
AHASEND_ACCOUNT_ID=your_account_id

Tymeslot Checks the Credentials After Startup

Whichever provider you pick, Tymeslot makes one cheap API call shortly after boot to confirm the credentials are accepted, and logs a prominent error if they are not. No email is sent by that check, and a failed check does not stop the app, so check the boot logs for mailer validation messages before relying on delivery. A value of EMAIL_ADAPTER that Tymeslot does not recognise, by contrast, stops the app at startup rather than quietly discarding every message.

3 Restart Tymeslot and Send a Test Email

1 Save your updated .env file and restart Tymeslot. It reads environment variables only at startup, so changes take effect only after a restart. With Docker Compose, use docker compose up -d, which recreates the container with the new values; a plain restart keeps the old ones.
2 Go to your Tymeslot sign-in page, click Forgot password?, then enter your account email address and submit. This sends a real email through your new mail settings.
3 Check your inbox. The password reset email should arrive within a few seconds. If it has not appeared after two minutes, check your spam folder before digging further.
4 If the email still has not arrived, search the container logs for delivery errors:

docker compose logs tymeslot | grep -Ei 'email|smtp|mailer'

If emails send but land in spam

Spam placement comes from your sending domain's DNS, not from Tymeslot. Add SPF, DKIM and DMARC records for your sending domain; your SMTP provider's documentation lists the exact values. Without them, many mail servers treat your email as suspicious whatever the message says.

❓ Frequently Asked Questions

Emails aren't being sent. How do I troubleshoot?

Start by inspecting the application logs for SMTP errors:

docker compose logs tymeslot | grep -Ei 'email|smtp|mailer'

The most common causes are incorrect credentials, a firewall blocking the outbound port, or a TLS mismatch between your SMTP_PORT and what the provider expects on that port. Compare the table in Step 1 with your provider's documentation.

At startup, Tymeslot connects to the relay and completes the same TLS handshake a real send makes. If that fails, it logs Mailer configuration validation failed with a suggested fix, so check the first lines of the log after a restart. Your username and password are only checked when the first email is sent.

Which SMTP port should I use?

Port 587 with STARTTLS is the modern standard; use it whenever your provider supports it. Port 465 uses implicit TLS (the connection is encrypted from the first byte); Tymeslot selects the right mode automatically for both ports. A provider that serves implicit TLS on any other port needs SMTP_SSL=true as well. Avoid port 25. It was the original SMTP port, but most cloud providers (AWS, GCP, Azure, DigitalOcean) block outbound connections on it to stop spam.

My own mail server fails with a certificate or TLS error. Why?

Tymeslot verifies the relay's certificate against the system trust store, and a mail server you host yourself usually serves a self-signed certificate, which no public trust store can validate. Other tools may connect where Tymeslot does not because they have an "ignore certificate errors" switch turned on.

Point SMTP_CACERTFILE at a PEM bundle holding the certificate authority that issued it. If there is no such authority (the certificate signs itself), set SMTP_TLS_VERIFY=none. The connection stays encrypted, but Tymeslot no longer checks who is on the other end.

The relay works for other mail clients, but Tymeslot times out or is cut off. Why?

A firewall or proxy between Tymeslot and the relay may be dropping TLS 1.3 handshakes it does not recognise. Set SMTP_TLS_MIDDLEBOX_COMPAT=true to make the handshake look like TLS 1.2 on the wire. Otherwise leave it off: against a relay that does not expect it, it breaks every send.

Gmail or Outlook refuses my credentials. Why?

Gmail rejects your normal account password for SMTP. Follow the App Password steps in the Gmail section above: the 16-character App Password is the only credential Gmail accepts.

Microsoft is phasing out password sign-in (Basic authentication) for SMTP on Outlook.com and Microsoft 365, and Tymeslot's SMTP adapter signs in with a username and password. If Microsoft rejects your credentials, send through a transactional provider such as Postmark, SendGrid or Amazon SES instead.

Can I use Amazon SES with Tymeslot?

Yes. Amazon SES offers a standard SMTP interface, so it works with the SMTP adapter. Follow the Amazon SES section in Step 2 to create dedicated SMTP credentials. Do not use your IAM access key and secret: SES generates a separate SMTP username and password.

Use the SMTP endpoint hostname for your SES region (shown on the SES SMTP Settings page) and port 587. Verify your sending domain or address in SES Verified Identities before attempting to send.

Emails are going to spam. How do I improve deliverability?

Spam placement almost always comes down to DNS. Add these three record types for your sending domain:

SPF: a TXT record listing the mail servers allowed to send for your domain
DKIM: a cryptographic signature proving the email was not altered in transit; your SMTP provider generates the key pair and gives you the TXT record to add
DMARC: a policy record telling receiving servers what to do when SPF or DKIM checks fail

If deliverability is still poor after adding those records, switch from your own SMTP server to a transactional email service such as Postmark or Mailgun. These services maintain their own sending reputation and handle bounces and complaints for you.

Verify Your Setup

Work through this checklist to confirm email works end to end.

Password reset email arrives. Trigger a reset from the sign-in page and confirm the email reaches your inbox from the right sender address.
Booking confirmation arrives after a test booking. Create a test meeting type, book it with a second email address, and confirm the attendee's confirmation arrives.
Host notification arrives after a test booking. The same test booking also sends a notification email to the host account.
FROM address is correct. Both emails show the name and address you set in EMAIL_FROM_NAME and EMAIL_FROM_ADDRESS, not a provider default.
Emails land in inbox, not spam. If they go to spam, set up SPF, DKIM and DMARC records for your sending domain before going live.

🔗 Related Articles

Email Setup: Postmark

Configure Postmark for Tymeslot transactional email. Covers domain verification, DKIM/SPF setup, and delivery tracking for better deliverability than standard SMTP.