SMTP Setup

kuploy-cloud requires SMTP for email delivery in production. Email is used for user verification, password resets, billing alerts, and notification channels.

Delivery mode: managed vs BYO

Before touching SMTP at all, check which delivery mode your instance is in. Admin → Email Delivery has a Delivery mode card at the top with two settings:

Mode	How platform mail is sent	SMTP settings
Managed — via kuploy.app plan (default)	Through the licensing hub, on your kuploy.app plan. No SMTP of your own is needed.	Unused. They apply only if you switch to BYO.
BYO — your own SMTP	Through the SMTP server you configure on the same page.	Required. Everything below applies.

Managed mode is the default unless you have explicitly switched. The SMTP form and the provider list on that page are hidden while you are in managed mode, because they would do nothing — that is not a bug, it is the page telling you which setting is live.

Managed mode does not silently fall back to SMTP

If the hub is unreachable, sends fail loudly rather than going out through a different server under a mismatched From identity. Identity-bearing mail (verification, billing) must be recognisably from you or not sent at all.

Switch modes with the button on the Delivery mode card. You can send a test message through either transport independently, which works even when no SMTP is configured.

The rest of this page covers BYO mode.

Why SMTP Is Required

Without SMTP configured:

• Users cannot verify their email addresses
• Password reset flows won't work
• Email-based billing notifications are disabled
• Team invite emails cannot be sent

Configuration Methods

SMTP can be configured through the admin dashboard or environment variables. Dashboard settings take priority over environment variables.

Method 1: Admin Dashboard (Recommended)

1. Log in as a platform admin
2. Go to Admin → SMTP
3. Enter your SMTP settings
4. Click Test to verify
5. Click Save

Settings are stored encrypted in the database and take effect immediately — no restart required.

Method 2: Environment Variables

Set these in your .env file or Kubernetes secret:

Variable	Description	Example
SMTP_HOST	SMTP server hostname	smtp.mailgun.org
SMTP_PORT	SMTP port	587
SMTP_USER	Authentication username	postmaster@mg.example.com
SMTP_PASS	Authentication password	your-smtp-password
SMTP_FROM	Sender email address	noreply@example.com
SMTP_FROM_NAME	Sender display name	My Platform

Method 3: Kubernetes Secret

For Kubernetes deployments:

# Encode values
echo -n "smtp.mailgun.org" | base64

# Patch the secret
kubectl patch secret kuploy-secrets -n kuploy -p '{
  "data": {
    "SMTP_HOST": "<base64-host>",
    "SMTP_PORT": "<base64-port>",
    "SMTP_USER": "<base64-user>",
    "SMTP_PASS": "<base64-pass>",
    "SMTP_FROM": "<base64-from>"
  }
}'

# Restart to apply
kubectl rollout restart deployment/kuploy -n kuploy

Recommended Providers

Any SMTP service works. Common choices:

Provider	Free Tier	Notes
Mailgun	100 emails/day	Popular for transactional email
SendGrid	100 emails/day	Easy setup, good deliverability
Amazon SES	62,000/month (with EC2)	Cheapest at scale
Postmark	100 emails/month	Focused on transactional email
Resend	3,000 emails/month	Modern API, developer-friendly
Brevo	300 emails/day	SMTP relay; free tier with no credit-card requirement

Brevo SMTP relay

If you choose Brevo, use its SMTP relay credentials (not the API key) for kuploy-cloud:

Variable	Value
SMTP_HOST	smtp-relay.brevo.com
SMTP_PORT	587
SMTP_USER	The login email shown in Brevo → SMTP & API → SMTP
SMTP_PASS	The SMTP key generated on the same screen
SMTP_FROM	A sender address from a domain you have verified in Brevo

Verify a sender domain in Brevo (Senders, Domains & Dedicated IPs → Domains) before sending — unverified senders are rejected.

Testing

After configuration, verify SMTP is working:

1. Admin dashboard test — Go to Admin → SMTP → click Test
2. Sign-up flow — Create a new user account and check for the verification email
3. Check spam folders — Transactional emails sometimes land in spam initially

Troubleshooting

Emails not sending

• Verify SMTP credentials are correct
• Check that the SMTP port is not blocked by your firewall
• Ensure the "from" address is verified with your SMTP provider

Emails going to spam

• Set up SPF, DKIM, and DMARC records for your sending domain
• Use a dedicated sending domain (not a free email provider)
• Ensure the "from" address matches your domain

Connection timeout

• Port 587 (STARTTLS) is recommended — port 25 is often blocked
• Check that your Kubernetes cluster allows outbound connections on the SMTP port
• Verify the SMTP host is resolvable from within your cluster