JavaScript disattivato Questa applicazione richiede JavaScript per funzionare. Abilitalo nelle impostazioni del browser. Aggiorna la pagina

Connessione persa

Tentativo di riconnessione in corso

Back to Overview

Email Setup: SMTP and Provider APIs

Configure outgoing email via SMTP or a provider's API. Required for booking confirmations, password resets, and meeting reminders.

Luka Breitig

Software Engineer & 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 — or an API key from a supported provider
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

Every automated notification Tymeslot sends goes out over email, so this must be configured. 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

Environment variable reference

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.

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:

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 — 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

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:

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. 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

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:

In the AWS console, navigate to [Amazon SES] → [SMTP Settings].
Click Create SMTP Credentials. AWS creates a dedicated IAM user behind the scenes.
Download the credentials file shown. 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 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

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

Port 465 vs 587

Set SMTP_PORT=465 only when your provider explicitly requires implicit TLS — Tymeslot selects it automatically for that port. Port 587 uses STARTTLS, is the modern standard, and is preferred; any other port falls back to opportunistic TLS.

🔀 Alternative: Send Through a Provider's API

Some providers can be used through their HTTP API instead of SMTP. The emails are identical — the difference is the transport. Reach for 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\nPOSTMARK_API_KEY=your_server_api_token

SendGrid

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

EMAIL_ADAPTER=sendgrid\nSENDGRID_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 — leaving it out sends your mail at the US endpoint, which will reject the key.

EMAIL_ADAPTER=mailgun\nMAILGUN_API_KEY=your_api_key\nMAILGUN_DOMAIN=mg.yourdomain.com\n# EU accounts only\nMAILGUN_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\nAHASEND_API_KEY=aha-sk-your_api_key\nAHASEND_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 — check the boot logs for mailer validation messages before assuming delivery works. 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. The application reads environment variables only at startup — changes take no effect until you restart.
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 mail provider.
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 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 mismatch between your SMTP_PORT and what the provider expects on that port. 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. Port 465 uses implicit TLS (the connection is encrypted from the first byte); Tymeslot selects the right mode automatically from SMTP_PORT alone, so no separate TLS variable is needed. 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) 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 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

Email Setup: Postmark

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