Running without email

BookYourPTO sends every account email — verification, welcome, password reset, digests, reminders — through an SMTP server you supply. A self-hosted install that has not configured one can still be set up and used: each step that normally arrives by email also exposes a link an administrator can copy and hand over directly.

This page covers running a self-hosted install with no SMTP at all. If you do have a mail server and want to connect it, see Email Configuration (SMTP).

When the application considers email unavailable

Before sending anything, BookYourPTO resolves an email configuration in this order:

1. The organization's own SMTP settings, configured under Settings → Email Configuration. All of host, port, username, password, and from-address must be present.
2. Platform SMTP from the environment — SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASSWORD, and SMTP_FROM_ADDRESS. All five must be present.
3. Nothing. If neither set is complete, the install has no email capability.

A partially filled set counts as nothing. Setting SMTP_HOST but leaving SMTP_PASSWORD empty does not give you a half-working mail path — it gives you the third case.

Creating the first organization

Registration is not blocked by the absence of email.

When you register an organization, the application tries to send a verification email. If there is no email configuration, or the send throws an error, the new account is marked verified instead and the verification step is skipped entirely. You are signed in and taken straight to organization setup — the "check your inbox" screen never appears, because there is no message coming.

The account created by registration is an Executive — the highest role — and it becomes the head of the default department created alongside the organization.

Adding users and sharing the setup link

Open Add User from the Users directory. If the install has no SMTP configured, the form shows an SMTP Not Configured warning before you submit, telling you the setup email will not go out.

Create the user as normal. On the confirmation screen you will see an Account setup link field with a copy button:

• If the welcome email was sent, the field holds the same link the email contains. Copy it only if you would rather deliver it yourself.
• If the welcome email was not sent, the field is the only way for the new user to set a password. Send it to them over whatever channel you use — chat, SMS, or in person.

The link points at /setup-account and is valid for 14 days. New-user invites get a deliberately long window because administrators often create accounts days or weeks before someone actually starts.

When the invited user opens the link, they choose a password. Completing that step also:

• clears the forced password change on their account,
• marks their email address as verified, which lifts the notification restrictions described below.

Resetting a user's password

From the Users directory, open a user's action menu and choose Reset Password. The API permits this for administrators and executives only, and only an executive may reset another executive's password.

The confirmation dialog states what is about to happen. When you accept:

• A new reset link is generated and shown to you in a Password reset link copy field, whether or not the email was delivered.
• The target user's existing sessions are all signed out immediately. They cannot keep working on another device while you arrange to get them the link.
• The reset link is valid for 1 hour.

The short window is deliberate: unlike a 14-day invite, an admin-initiated reset is something you perform while the person is waiting. Plan to hand the link over straight away. If it lapses, run the action again.

Link expiry at a glance

The self-service route still depends on email — nothing is delivered without SMTP — so on an install without a mail server, the administrator reset is the only working path.

How the links are handled

The links are safe to use this way, but they are still credentials. Treat them accordingly.

• Only a digest is stored. The database holds a SHA-256 hash of the token, never the token itself. Reading the database does not yield a usable link.
• The link is returned once, to you. It appears in the HTTP response to the administrator who performed the action and nowhere else. It is deliberately kept out of the audit log — which every other administrator in the organization can read — and out of the server logs.
• Anyone holding the link can set that account's password until it expires or is used. Send it over a private channel, not a shared one.
• The copy field builds the link from the address bar. It takes a path and prefixes the origin you are currently browsing, so a link copied from http://192.168.1.20:3010 points back at that host rather than at a public address the install does not answer on.

The audit log still records that a reset was performed, by whom, against which user, and whether an email was sent.

What a user should do when no email arrives

Someone who uses Forgot password on an install without SMTP will see the "check your email" screen and nothing will ever arrive. That screen now says so, and tells them to ask an administrator to generate a reset link from the Users page.

If a user reports this, run Reset Password for them and hand over the link. Remember that doing so signs them out everywhere and gives them one hour to use it.

Notifications you will not receive

Without SMTP, no email leaves the install. That covers every automated message: leave submissions, approvals, rejections and cancellations, approval requests waiting on someone, low-balance and carry-over warnings, upcoming leave reminders, expense, document, training and onboarding activity, scheduled digests, and the account emails themselves.

What continues to work:

• In-app notifications. Every notification is written to the recipient's notification list regardless of email, so nothing is lost — people just have to look in the application rather than in their inbox.
• Organization-wide Slack and Microsoft Teams webhooks, where your plan includes notification channels. These are addressed to a shared channel rather than to an individual, so they fire normally.

There is a second restriction worth knowing about, because it applies whether or not you have SMTP. A user whose email address is not yet verified — which is every invited user until they complete their setup link — does not receive:

• non-account email (account email such as the welcome and reset messages is exempt, which is what makes the invite work at all),
• notifications through their personal Slack or Teams webhook,
• mobile push notifications.

Those resume the moment they complete setup. Organization-wide channels are unaffected, since the rest of the team is still expecting those messages.

Set APP_URL anyway

The copy fields described above work without any configuration, because they build the link from the address you are browsing. Other links do not have that luxury.

Emails, notification action links, and OAuth redirects are generated on the server, where there is no address bar to read. They resolve the application's base URL in this order:

1. The organization's verified white-label custom domain, if it has one.
2. The APP_URL environment variable.
3. The hosted BookYourPTO address, as a last resort.

On a self-hosted install with APP_URL unset, that last resort means links pointing at an address your users have no account on. Set APP_URL in your .env to the address people actually use to reach your install:

APP_URL="https://pto.example.com"

It must be a complete origin including the scheme. A bare hostname or a path is rejected and treated as unset.

This matters as soon as you configure SMTP, and it already matters for Slack, Teams, and push notification links, which carry a link back into the application.

Adding email later

Nothing about the steps above has to be undone. Configure SMTP under Settings → Email Configuration, or set the platform SMTP_* variables, and the next action that sends an email will use it. Existing users keep their accounts, their verification state, and their passwords.

See Email Configuration (SMTP) for the settings themselves, and SMTP troubleshoot if authentication fails against Microsoft 365.