Licensed to be used in conjunction with basebox, only.
// integration
SMTP
Applies to
Product: Cloud · Server · Audience: Administrator · Platform Operator
Outgoing mail for invitations and notifications: which settings are needed, how to test the configuration before saving, and what happens without SMTP.
What basebox sends mail for
- Invitations of new users (valid for 14 days) and their re-sending
- Password reset
- Further notifications of the application
Without working mail delivery, invitations do not arrive. basebox therefore warns when users are invited although no SMTP is configured. As a stopgap you can copy the invitation link in the Invitations tab and deliver it another way.
Settings
| Setting | Meaning | Typical value |
|---|---|---|
| SMTP host | Your mail server | smtp.company.com |
| Port | Connection port | 587 (STARTTLS) or 465 (TLS) |
| Username / password | Credentials of a sending account | dedicated service account |
| Connection type | starttls or tls |
starttls with 587, tls with 465 |
| Sender address | From address of the mails | noreply@company.com |
Use a dedicated service account with send permission for the sender address, not a person's mailbox. Make sure your domain's SPF/DKIM allow sending via this server so invitations do not land in spam.
Where mail delivery is set up
Mail delivery is the first step of the initial setup: without it, invitations do not arrive.
- basebox Cloud: The SMTP configuration is not on the Administration → Organisation page. In the cloud, too, you connect your own mail server; basebox does not provide mail delivery. Arrange the setup with support@basebox.ai.
- basebox Server: The Platform Operator sets the mail parameters via Helm (see below).
Where a mail configuration is offered in the interface, it can be tested before saving: basebox establishes the connection and reports whether it succeeds. Then:
- Enter host, port, username, password, connection type and sender address. Use a technical mailbox, not a personal one.
- Test the connection. On failure, read the message – usually port and connection type are mixed up or the credentials are wrong.
- Save.
- Invite a user as a trial (for example yourself) and check that the e-mail arrives, including the spam folder.
Mail credentials are secrets
Use a dedicated technical account for SMTP with permission to send only. The password is not shown again after saving.
On basebox Server via configuration
Alternatively, the Platform Operator can set the mail parameters in the application server's Helm values – credentials as a Kubernetes secret, not in clear text:
aisrv:
env:
AISRV_SMTP_HOST: "smtp.company.com"
AISRV_SMTP_PORT: "587"
AISRV_SMTP_TLS_TYPE: "starttls"
AISRV_SENDER_EMAIL: "noreply@company.com"
AISRV_SMTP_USERNAME:
valueFrom:
secretKeyRef:
name: smtp-credentials
key: username
AISRV_SMTP_PASSWORD:
valueFrom:
secretKeyRef:
name: smtp-credentials
key: password
Reference: AISRV → SMTP configuration.
Network
The application server must reach your mail server on the chosen port (outbound TCP 587 or 465). On basebox Server that is a firewall rule in your network. In basebox Cloud, your mail server must be reachable from basebox's data centre (noris network, Munich) – or you use an internet-facing relay service of your organisation.
In fully air-gapped operation there is no path outwards; use an internal mail server or distribute invitation links manually.
Troubleshooting
| Symptom | Cause | Solution |
|---|---|---|
| Connection test fails immediately | Host/port wrong, firewall | Check DNS and port; telnet smtp.company.com 587 from the server |
| TLS error | Connection type does not match the port; private certificate | starttls↔587, tls↔465; check CA trust |
| Authentication rejected | Credentials, missing send permission | Check service account; app password instead of normal password with some providers |
| Mails do not arrive | Spam filter, SPF/DKIM | Authorise the sender domain; check the spam folder |
| Invitation expired | 14 days exceeded | Renew in the Invitations tab |
Frequently asked questions
Why do invitation e-mails not arrive? Check the connection test, the sender address and the recipient's spam filter. Without an SMTP configuration no e-mails are sent; you can then copy the invitation link in the Invitations tab and deliver it yourself.
Next step: Set up the organisation · Invite users