Back to Overview

Email Setup: SMTP

Configure outgoing email via SMTP. Required for booking confirmations, password resets, and meeting reminders.

Luka Breitig — Technical Product Builder & AI Developer
Luka Breitig

Technical Product Builder & AI Developer

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
  • A verified sending domain, or at minimum a sending address your provider permits
  • Ability to restart the Tymeslot process after updating environment variables

By the end of this guide, Tymeslot will send booking confirmations, password reset emails, and meeting reminders through your SMTP server.

Why Email Configuration Is Required

Email is not optional — it is the delivery mechanism for every automated notification Tymeslot sends. Without it, these flows break silently: your instance appears to work, but attendees never receive confirmations and hosts never know a booking arrived.

Tymeslot sends email for:

  • Booking confirmation to attendee — sent immediately when someone books a slot
  • Booking notification to host — alerts you when a new meeting is booked
  • Cancellation and rescheduling notices — sent to both host and attendee
  • Meeting reminders — configurable timing before each appointment
  • Password reset — users cannot recover their account without this
  • Magic link sign-in — passwordless login links
  • Team invitations — invite links sent to new team members

1 Set the Core Environment Variables

Open your .env file (or your hosting platform's environment variable settings) and add all of the following. Every variable is required.

These apply to all SMTP providers — the provider-specific sections below replace 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
SMTP_SSL=false
SMTP_TLS=true
Variable Purpose
EMAIL_ADAPTER Must be smtp for generic SMTP. Use postmark for Postmark's native adapter.
EMAIL_FROM_NAME The display name recipients see in their inbox — e.g., "Acme Corp"
EMAIL_FROM_ADDRESS The FROM address recipients see. Must match a domain your SMTP server permits you to send from.
SMTP_PORT 587 for STARTTLS (recommended). 465 for implicit TLS. Avoid 25 — most cloud providers block it.
SMTP_SSL Set to true only when using port 465 (implicit TLS). Leave false for port 587.
SMTP_TLS Set to true to enable STARTTLS on port 587. Set to false when using port 465.

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. You must generate an App Password — a 16-character token that grants SMTP access without exposing your main account password.

To create an App Password:

  1. 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.
  2. On the same Security page, search for or scroll to App passwords and open it. You may be prompted to sign in again.
  3. In the App name field, type "Tymeslot" and click Create.
  4. Google displays a 16-character password. Copy it now — it is shown only once. Use this as SMTP_PASSWORD.

After completing those steps, you should see the App Password listed under your account's app passwords. Your Tymeslot instance is now authorized to send via Gmail. 

SMTP_HOST=smtp.gmail.com\nSMTP_PORT=587\nSMTP_USERNAME=your.address@gmail.com\nSMTP_PASSWORD=xxxx xxxx xxxx xxxx\nSMTP_SSL=false\nSMTP_TLS=true

If you get "534 Username and Password not accepted"

You are using your regular Google account password. Gmail rejects it for SMTP. Return to Step 2 above and generate an App Password — that is the only credential Gmail accepts here.

Gmail is for Low-Volume Deployments

Free Gmail accounts are capped at 500 emails per day. Google Workspace accounts raise this to around 2,000. For production deployments with steady booking activity, use a dedicated transactional service like SendGrid or Amazon SES.

SendGrid

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

To get your API key:

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

After creation, you are returned to the API Keys list. The new key appears with the name you chose. Your sending domain must also be verified under [Settings] → [Sender Authentication] before emails will be delivered. 

SMTP_HOST=smtp.sendgrid.net\nSMTP_PORT=587\nSMTP_USERNAME=apikey\nSMTP_PASSWORD=SG.your_api_key_here\nSMTP_SSL=false\nSMTP_TLS=true

Amazon SES

SES SMTP credentials are not your AWS access key and secret — they are a separate set of credentials generated specifically for SMTP. Do not use your IAM access keys here.

To generate SES SMTP credentials:

  1. In the AWS console, navigate to [Amazon SES] → [SMTP Settings].
  2. Click Create SMTP Credentials. AWS creates a dedicated IAM user behind the scenes.
  3. Download the credentials file shown. The SMTP Username (starts with AKIA) and SMTP Password go into your environment.
  4. 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 changes by region — use the one shown on the SMTP Settings page. 

SMTP_HOST=email-smtp.eu-west-1.amazonaws.com\nSMTP_PORT=587\nSMTP_USERNAME=AKIAIOSFODNN7EXAMPLE\nSMTP_PASSWORD=your_ses_smtp_password\nSMTP_SSL=false\nSMTP_TLS=true

SES Sandbox Mode

New SES accounts start in sandbox mode. In this mode, you can only send to verified email addresses — your own test addresses. To send to any recipient, submit a production access request through [Account Dashboard] → [Request Production Access]. AWS typically approves this within one business day.

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

Any provider that exposes standard SMTP works with Tymeslot. Locate the SMTP credentials section in your provider's documentation or dashboard — you need the hostname, port, username, and password. 

SMTP_HOST=smtp.your-provider.com\nSMTP_PORT=587\nSMTP_USERNAME=your_smtp_username\nSMTP_PASSWORD=your_smtp_password\nSMTP_SSL=false\nSMTP_TLS=true

Port 465 vs 587

Use SMTP_PORT=465, SMTP_SSL=true, and SMTP_TLS=false only when your provider explicitly requires port 465 with implicit TLS. Port 587 with STARTTLS is the modern standard and is preferred.

3 Restart Tymeslot and Send a Test Email

  1. 1 Save your updated .env file and restart Tymeslot. The application reads environment variables only at startup — changes take no effect until you restart.
  2. 2 Navigate to your Tymeslot sign-in page and click Forgot password?. Enter your account email address and submit. This triggers a real outbound email through your newly configured SMTP server.
  3. 3 Check your inbox. The password reset email should arrive within a few seconds. If it does not appear within two minutes, check your spam folder before investigating further.
  4. 4 If the email did not arrive, inspect the container logs for delivery errors: 
docker-compose logs tymeslot | grep -Ei 'email|smtp|mailer'

If emails send but land in spam

This is a DNS configuration issue, not an application issue. You need to add SPF, DKIM, and DMARC records for your sending domain. Your SMTP provider's documentation will list the exact DNS record values. Without these records, many mail servers will mark your email as suspicious regardless of what is in the message body.

❓ 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/SSL mismatch between your SMTP_PORT, SMTP_SSL, and SMTP_TLS values. Cross-reference the table in Step 1 against what your provider's documentation specifies.

Which SMTP port should I use?

Port 587 with STARTTLS is the recommended modern standard — use it whenever your provider supports it (SMTP_SSL=false, SMTP_TLS=true). Port 465 uses implicit TLS (the connection is encrypted from the first byte) and requires SMTP_SSL=true and SMTP_TLS=false. Avoid port 25 — it was the original SMTP port but most cloud providers (AWS, GCP, Azure, DigitalOcean) block outbound connections on it to prevent spam abuse.

Gmail or Outlook refuses my credentials — why?

Both Google and Microsoft block standard account passwords for SMTP when two-factor authentication is enabled. You must use an app-specific password instead.

For Gmail, follow the App Password steps in the Gmail section above — a 16-character token is the only credential Gmail will accept for SMTP. For Microsoft 365 / Outlook, go to account.microsoft.com → Security → Advanced security options → App passwords and generate one there. Standard account passwords will always be rejected.

Can I use Amazon SES with Tymeslot?

Yes. Amazon SES exposes a standard SMTP interface and works with the generic SMTP adapter. Follow the Amazon SES section in Step 2 to generate dedicated SMTP credentials (do not use your IAM access key and secret directly — SES generates a separate SMTP username and password).

Use the SMTP endpoint hostname for your SES region (shown on the SES SMTP Settings page), port 587, SMTP_SSL=false, and SMTP_TLS=true. 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 is almost always a DNS configuration problem, not an application one. Add these three DNS record types for your sending domain:

  • SPF — a TXT record that lists which mail servers are authorised to send on behalf of your domain
  • DKIM — a cryptographic signature that proves the email was not tampered with in transit; your SMTP provider generates the key pair and gives you the TXT record to add
  • DMARC — a policy record that tells receiving servers what to do when SPF or DKIM checks fail

If you continue to have deliverability problems after adding those records, consider switching to a dedicated transactional email service such as Postmark or Mailgun rather than raw SMTP — they maintain their own sending reputation and handle much of this automatically.

Verify Your Setup

Work through this checklist to confirm everything is working end to end.
  • Password reset email arrives — trigger a reset from the sign-in page and confirm the email reaches your inbox from the correct FROM address.
  • Booking confirmation arrives after a test booking — create a test event type, book a meeting using a second email address, and confirm the attendee confirmation arrives.
  • Host notification arrives after a test booking — the same test booking above should also deliver a notification email to the host account.
  • FROM address is correct — both emails should 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 are going to spam, configure SPF, DKIM, and DMARC records for your sending domain before going live.

🔗 Related Articles

Read Email Setup: Postmark

Email Setup: Postmark

Send transactional email through Postmark for high deliverability and detailed delivery analytics.

Read Telegram Notifications

Telegram Notifications

Receive instant Telegram messages for every new booking, cancellation, or reschedule. One shared bot, zero credentials for users.

Read Docker Self-Hosting

Docker Self-Hosting

Deploy Tymeslot using Docker and Docker Compose. Perfect for VPS hosting, home servers, or any environment with Docker support.