Domains, Senders & SMTP

Forge separates email into two production boundaries:

• Email domain — the project-owned sending domain, such as novianow.com. Forge verifies ownership before any sender can use it.
• Sender identity — one address on a verified domain, such as noreply@novianow.com or support@novianow.com. Each sender has its own DKIM key, quota, send logs, and SMTP policy. API keys can be scoped either to one sender or to the whole project.

A project can own multiple email domains, and a verified domain can have multiple senders. Forge itself can also have system-owned sender identities for platform mail.

Add an Email Domain

1. Open the project.
2. Go to Email → Domains.
3. Click Add Domain.
4. Enter the project-owned sending domain, for example novianow.com.
5. Add the TXT record Forge shows.

Most DNS providers need:

Type:  TXT
Name:  _forge-mail.novianow.com
Value: forge-verify-xxxxxxxxxxxxxxxxxxxxxxxx

If your DNS provider automatically appends the root domain, use the short host:

Type:  TXT
Name:  _forge-mail
Value: forge-verify-xxxxxxxxxxxxxxxxxxxxxxxx

Click Verify after publishing the record. DNS propagation can take a few minutes.

Add a Sender Identity

After the email domain is verified:

1. Go to Email → Identities.
2. Click Add Sender.
3. Choose a verified domain.
4. Enter the from address and display name.
5. Keep the default SMTP transport unless you need an advanced override.

Field	Example	Description
Verified Domain	novianow.com	Must already be verified in the Domains tab
From Address	noreply@novianow.com	The address emails appear to come from
Display Name	Novia	Appears as the sender name: Novia <noreply@novianow.com>
Daily Quota	1000	Max sends per day for this sender
SMTP Host	mail.forgecloud.cc	Default same-VPS MTA hostname
SMTP Port	587	587 for STARTTLS, 465 for implicit TLS
Require STARTTLS	On	Required for the default same-VPS Postfix setup
SMTP Username / Password	blank	Blank means trusted local SMTP. Fill these only for authenticated SMTP providers.

DKIM Verification

Each sender identity gets its own DKIM key. Publish the TXT record shown on the identity card:

Type:  TXT
Name:  forge-ab12cd34ef._domainkey.novianow.com
Value: v=DKIM1; k=rsa; p=MIIBIjANBgkq...

If your provider auto-appends the root domain, use the short host:

Type:  TXT
Name:  forge-ab12cd34ef._domainkey
Value: v=DKIM1; k=rsa; p=MIIBIjANBgkq...

Click Verify after the DKIM TXT record is visible. The sender should only be used for production sends after both the domain ownership and sender DKIM checks pass.

Supported SMTP Providers

Forge works with any RFC-compliant SMTP server:

Provider	Host	Port	Notes
Gmail	smtp.gmail.com	587	Requires app password (not your regular password)
Self-hosted Postfix	mail.yourdomain.com	587	Your own mail server
Mailcow	mail.yourdomain.com	587	Self-hosted email suite
AWS SES SMTP	email-smtp.us-east-1.amazonaws.com	587	Requires SES SMTP credentials (different from IAM)
Proton Mail Bridge	127.0.0.1	1025	Local bridge only — same server as Forge
Mailgun SMTP	smtp.mailgun.org	587	If you prefer Mailgun’s SMTP relay over their API

Same-VPS Postfix Notes

For the default same-VPS setup, Forge connects to Postfix on the mail hostname:

mail.forgecloud.cc:587

Use FORGE_EMAIL_SMTP_REQUIRE_TLS=true so new identities require STARTTLS by default. The mail hostname should resolve locally to the VPS, and Postfix should present the certificate for that same hostname.

Postfix must trust both loopback and the VPS host IPs in mynetworks. Some SMTP clients may reach Postfix from the VPS public IP even when /etc/hosts maps the mail hostname to 127.0.0.1. If that IP is not trusted, Postfix rejects outbound recipients with:

554 5.7.1 Relay access denied

The Forge MTA installer auto-detects non-Docker host IPs. If you need to override it, set:

FORGE_EMAIL_MTA_TRUSTED_NETWORKS="127.0.0.0/8, [::1]/128, VPS_PUBLIC_IP/32, VPS_PRIVATE_IP/32"

OpenDKIM should run as opendkim:postfix so Postfix can write to the chroot-visible milter socket.

API Keys

API keys authenticate requests to the send and broadcast endpoints. Forge supports two useful scopes:

• Project key — can send from any verified sender identity in the project. Include from in API requests when a project has more than one sender.
• Sender key — can only send from one sender identity.

Creating a Key

1. Open the project and go to Email → API Keys
2. Choose Project key or Sender key
3. For sender keys, select the identity
4. Name your key (e.g., “Production”, “Staging”)
5. Select scopes:
   • Send — transactional email
   • Automation — trigger webhooks
   • Broadcast — send to lists
   • All — everything
6. Click Create — the full key is shown once

Key Format

ef_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• Prefix: ef_ (email forge)
• Body: 32 random characters
• Stored as SHA-256 hash — Forge never stores the plaintext key

Using a Key

Include the key in the Authorization header:

curl -X POST https://forge.yourdomain.com/api/v1/email/send \
  -H "Authorization: Bearer ef_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"from": "noreply@novianow.com", "to": ["user@example.com"], "subject": "Hello", "text_body": "World"}'

Revoking a Key

Click Revoke on any key in the dashboard. Revoked keys cannot be re-activated — create a new one instead.

Daily Quotas

Each identity has a daily sending limit:

• Default: 1,000 sends/day
• Configurable: Click the identity → edit Daily Quota
• Counter resets: Midnight UTC
• 429 response when exceeded, with Retry-After header

Broadcasts count against the same quota. If you plan to send large broadcasts, increase the quota accordingly.

Security

• SMTP passwords are encrypted at rest using Forge’s secret key (FORGE_SECRET_KEY)
• API keys are hashed (SHA-256) — the full key is shown only once
• Keys are scoped — a leaked send key cannot trigger automations or broadcasts
• Keys are revocable — revoke and rotate without affecting other keys
• Domain verification prevents sending from domains you don’t own
• DKIM private keys are encrypted at rest and are unique per sender identity