GoAdmio

forwardemail

Set up a hosted domain to send its email through the Forward Email SMTP service: add the domain there, create an SMTP password, add the DNS records on Cloudflare, and save the SMTP settings in GoAdmio

On this page: Overview · Quick start · Syntax · Arguments · Output · Examples · Troubleshooting · Details · Risks · See also


Overview

Forward Email is an email service with an SMTP server for sending mail. /go/forwardemail connects one of your hosted domains to it, so that the domain's outgoing mail is sent through smtp.forwardemail.net and not directly from your server. This can help mail reach the inbox.

In one run it:

[!NOTE] Despite what the command index used to say, this is not the same as forward, which forwards mail from one address to another. forwardemail is for sending mail. It does not add MX records, so it does not change where incoming mail is delivered. See mx.

[!WARNING] Every run replaces the domain's SMTP password. The old password stops working, so anything that uses it must be updated.


Quick start

/go/forwardemail example.com

Write down the SMTP Password it prints. It is shown only in the output of this command.


Syntax

/go/forwardemail <domain>

The command writes the call and a timestamp to /var/log/go/forwardemail.log.


Arguments

Position Argument Required Notes
1 <domain> Yes A domain that is hosted on this server and has a zone in your Cloudflare account.

There is no all option. Run the command once for each domain. The domain is not checked before use, so always pass one.

What you need first


Output

SMTP Password: <the new password>

and the output of the cloudflare commands that add the DNS records.

Message Meaning
There is no Forward Email API Key No Forward Email token is saved. The command stops with status 1.
Cannot Get Cloudflare Zone ID for <domain>... The domain was not found in your Cloudflare account. The command stops with status 1.

The answers from Forward Email and Cloudflare are not shown, so a failed step does not print an error.


Examples

# Connect a domain to Forward Email
/go/forwardemail example.com
# Check the DNS records that were added
dig +short TXT example.com
dig +short CNAME fe-bounces.example.com
# Review recent calls
tail /var/log/go/forwardemail.log

Troubleshooting

Symptom Likely cause Fix
There is no Forward Email API Key The token is not saved in GoAdmio. Save your Forward Email API token, then run again.
Cannot Get Cloudflare Zone ID for <domain>... The domain is not in your Cloudflare account, or the Cloudflare credentials are wrong. Add the domain with dns, check the credentials, then run again. By then the domain is already added at Forward Email and the password is replaced, so run the command again to get a password that matches.
jq: command not found, or empty values jq is not installed. Install jq, then run again.
SMTP Password: is empty or says null Forward Email refused the request, for example because of a wrong token. Fix the token and run again. Mail for the domain may fail until you do, because the command turns the SMTP settings on anyway.
The domain stays unverified at Forward Email DNS needs more than the 5 seconds the command waits. Wait for DNS, then verify the domain in the Forward Email dashboard.
Sites on the domain cannot send mail The SMTP password was replaced, or the domain is not verified. Check the domain at Forward Email. Use the newest password.
The old SMTP password stopped working Every run creates a new password and deletes the first existing one. Update the programs that use it.
Incoming mail is not delivered as you expected The command does not change MX records. Use mx if needed.
A DNS record is missing The Cloudflare request failed without any message. Check Cloudflare. Add it with dkim, dmarc, txt, or cname.

Details

What it does

  1. Records the call in /var/log/go/forwardemail.log.
  2. Reads the Forward Email API token from /var/lib/sqlite/config.db. Stops if there is none.
  3. At Forward Email (api.forwardemail.net):
    1. Adds the domain.
    2. Deletes the first existing catch-all password.
    3. Creates a new catch-all password, which is the SMTP password.
    4. Reads the domain's DKIM record, DMARC record, and verification code.
  4. Looks up the domain's Cloudflare zone. Stops if it is not found.
  5. Adds the DNS records on Cloudflare (see below).
  6. Waits 5 seconds, then asks Forward Email to check the records.
  7. Prints the SMTP password.
  8. Saves the SMTP settings for the domain in /var/lib/sqlite/site.db.
  9. Runs vmail.
flowchart TD
    A["forwardemail domain"] --> B{"Forward Email token saved?"}
    B -- "No" --> X1["Print message, exit 1"]
    B -- "Yes" --> C["Add domain, replace SMTP password, read DNS values"]
    C --> D{"Cloudflare zone found?"}
    D -- "No" --> X2["Print message, exit 1"]
    D -- "Yes" --> E["Add DKIM, DMARC, verification, and bounce records"]
    E --> F["Wait 5 seconds, ask Forward Email to verify"]
    F --> G["Print password, save SMTP settings, run vmail"]

DNS records added on Cloudflare

Type Name Content
TXT (DKIM) The name Forward Email gives The value Forward Email gives
TXT (DMARC) _dmarc The DMARC value Forward Email gives
TXT (verification) The domain forward-email-site-verification= followed by the domain's code
CNAME (bounces) fe-bounces forwardemail.net

The SPF record is not changed by this command. Check Forward Email's instructions to see whether your SPF record needs an update, and see spf.

SMTP settings saved in GoAdmio

These are saved for the domain in the Site table, and the setting is turned on:

Setting Value
Host smtp.forwardemail.net
Port 587
User goadmio@<domain>
Password The new SMTP password
Active On

Risks


See also

Command Description
forward Set or remove forwarding for one email address
brevo Set up Brevo email sending for your domains
dkim Add a DKIM TXT record to a domain's Cloudflare DNS
dmarc Add a DMARC TXT record to a domain's Cloudflare DNS
spf Add or refresh the SPF TXT record via Cloudflare
txt Add a TXT record to a domain through Cloudflare
cname Add a CNAME record to a domain's DNS zone on Cloudflare
mx Add an MX record to a domain through Cloudflare
vmail Rebuild the Postfix/Dovecot vmail maps
dns Add hosted domains to Cloudflare and set up their DNS zone