Send email from Coolify

Two things on a Coolify server send email: the apps you deploy, and Coolify itself (deployment, backup and server alerts). Both can send through Groundmail from your own domain. Apps use the API key or the SMTP relay; Coolify's notifications use the SMTP relay.

Prerequisites

• A Groundmail account with a verified sending domain. A subdomain such as mail.yourdomain.com works well.
• For apps: an API key (gm_…) from API keys, or an SMTP credential if the app only speaks SMTP.
• For Coolify's notifications: an SMTP credential (gmsmtp_…) from SMTP in the dashboard. The password is shown once, so copy it.

Apps you deploy

Add the API key

1. In Coolify, open the application and select Environment Variables.
2. Add GROUNDMAIL_API_KEY with your key as the value. In Developer view you can paste it as a .env line instead.
3. Your app only needs the key at runtime, so set Build time to Not available during build. That keeps it out of the build logs and image layers.
4. Save, then Restart the app. (A Redeploy is only needed when a build-time value changes.)

Production and preview deployments have separate variable sections; add the key to each one that sends.

For a Docker Compose app, reference the variable in your compose file and Coolify lists it under Environment Variables for you to fill in. :? makes Coolify refuse to deploy while it's empty:

services:
  app:
    environment:
      - GROUNDMAIL_API_KEY=${GROUNDMAIL_API_KEY:?}

Send

Node.js

npm install groundmail

import { Groundmail } from 'groundmail'

const groundmail = new Groundmail(process.env.GROUNDMAIL_API_KEY)

await groundmail.emails.send({
  from: 'App <no-reply@mail.yourdomain.com>',
  to: 'user@example.com',
  subject: 'Reset your password',
  html: '<p>Click the link to reset your password.</p>',
})

Other stacks: Python, Go, PHP, Ruby, Laravel, Rails, or POST https://api.groundmail.dev/emails from anything: see the API reference.

Apps that only speak SMTP

Self-hosted apps such as Ghost, n8n, Plausible or WordPress take SMTP settings. Put the SMTP relay settings in their environment variables:

Coolify's own notification email

Coolify emails you about deployments, backups, scheduled tasks and servers. To send those through Groundmail:

1. In Coolify, open Notifications and select Email.
2. Set Email service to Use team email settings.
3. Fill in From name and From address (both required). The from address must be on your verified domain.
4. In the SMTP server section:

5. Click Save changes in the SMTP server section, then set SMTP delivery to enabled and save.
6. Under Notification events, pick the events you want, click Send test and enter an address you can read. The test shows up under Emails in the Groundmail dashboard with its delivery status.

Don't pick TLS/SSL: that's implicit TLS for port 465, which Groundmail doesn't offer, so the connection fails.

Several teams on one self-hosted instance? Put the same settings in Settings → Email once, send a test, then set each team's Email service to Use system-wide settings.

Troubleshooting

Related: SMTP relay · Tools with SMTP settings · Node.js SDK · Railway