Fondoo
GitHubStart your 7-day trial for $0Start trial
Docs

Connect an SMTP server to Fondoo

alternate_emailLive5 min readUpdated

This guide lets your Fondoo site send email through any SMTP server you already use. Examples include a mail host, your email provider's SMTP relay, or a transactional service's SMTP endpoint. Fondoo still decides who may receive each message, checks consent and suppressions, and keeps the delivery log. Your AI agent keeps using the normal Fondoo email operations, such as sendemail.

What Fondoo can do with it

  • Send transactional and marketing email for a site through your SMTP server, always over TLS.
  • Use SMTP for one site only, or as the default for the whole workspace. A site setting overrides the workspace setting.

What it cannot do:

  • SMTP has no event feed. Fondoo gets no delivery, bounce or complaint events from an SMTP connection. It records a message as failed only when the server refuses the recipient during sending.
  • Fondoo does not create SMTP accounts or DNS records for you.

Approvals and limits that still apply:

  • configure_email_provider and set_provider need the workspace owner.
  • Marketing email needs evidenced consent and a postal address set with update_email_settings.
  • An agent that sends more than 1,000 marketing emails for a site in a month needs your approval.
  • Each send_email call takes up to 100 recipients.

Before you start

  • SMTP login details from your mail provider: host name, port, username and password. Use the provider's submission settings, not your mailbox's incoming (IMAP/POP) settings.
  • A server that supports TLS. Fondoo never sends over an unencrypted connection. It accepts implicit TLS (usually port 465) or STARTTLS (usually port 587).
  • Your sending domain authenticated with that provider (SPF and DKIM). Follow your provider's own guide for this.
  • The same domain added and verified on your Fondoo site (set_custom_domain, then get_domain_status until it is active). Fondoo matches the From domain exactly.
  • Any costs come from your SMTP provider. Fondoo's per-site email overage charge does not apply to mail sent through your own provider.

Step by step: get your credentials

  1. In your mail provider's dashboard, find the SMTP or "SMTP relay" settings page. Create a dedicated SMTP user or app password for Fondoo if your provider allows it, so you can revoke it on its own. Two examples:
    • Amazon SES: SMTP settings → Create SMTP Credentials. SES SMTP credentials differ from AWS access keys and are specific to one Region (SES SMTP credentials).
    • Resend: host smtp.resend.com, username resend, password your API key (Resend SMTP).
  2. Build one connection URL from the four values. Fondoo stores SMTP settings as a single url:
    • Implicit TLS (port 465): smtps://USERNAME:PASSWORD@SMTP-HOST:465
    • STARTTLS (port 587): smtp://USERNAME:PASSWORD@SMTP-HOST:587. With smtp://, Fondoo requires STARTTLS and refuses to continue without it.
  3. Percent-encode any special characters in the username or password. For example @ becomes %40, : becomes %3A, / becomes %2F. This is the standard URL format used by the Nodemailer library that Fondoo uses (Nodemailer SMTP transport).
  4. Write down your sending domains in lowercase, for example example.com.

You now have:

Fondoo credential fieldWhat to put in it
url (required)The smtps:// or smtp:// URL from step 2
domains (required in practice)List of sending domains, lowercase

Connect it in Fondoo

In the dashboard. The Connections page lists an Email card, but it only opens setup instructions. There is no form for SMTP details yet. Use your agent or the REST API.

By asking your agent. Example prompt:

Use my SMTP server for this site's email. I will save the login myself. Then set up example.com as the sending domain and check it.

configure_email_provider takes the password directly in its input and has no secure paste page. Anything pasted into a chat can stay in chat logs, so run that call yourself over REST with an owner API key.

The calls, in order:

  1. configure_email_provider({siteId, provider:"smtp", credential:{url:"smtps://...", domains:["example.com"]}}). Leave out siteId to make it the workspace default. Fondoo rejects any URL that does not start with smtp:// or smtps://.
  2. set_provider({siteId, capability:"email", provider:"smtp"}).
  3. setup_sending_domain({siteId, domain:"example.com"}). Fondoo returns no DNS records for SMTP. It checks that the domain is in your domains list.
  4. check_sending_domain({siteId, domain:"example.com"}).

connect_service({provider:"smtp", siteId}) returns a signed 15-minute link with setup instructions. It never takes credentials.

REST equivalent:

curl -X POST https://api.getfondoo.com/v1/ops/configure_email_provider \
  -H "Authorization: Bearer $FONDOO_OWNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"YOUR-SITE-ID","provider":"smtp","credential":{"url":"'"$SMTP_URL"'","domains":["example.com"]}}'

Test that it works

  1. get_email_provider({siteId}) should show provider: "smtp". Its feedbackUrl is not used for SMTP.
  2. check_sending_domain({siteId, domain}) should return verified: true.
  3. Add yourself as a contact (create_contact) and send a transactional message with send_email({..., category:"transactional"}).
  4. Check list_emails({siteId}) for the status, and confirm the message arrived in your inbox. Look at the message headers to confirm SPF and DKIM passed.

Troubleshooting

  • "SMTP_URL must use smtp or smtps": the URL starts with something else, such as https://, or has a typo. Rebuild it as shown in step 2.
  • Login or connection failures: the wrong port for the scheme is the most common cause. Use smtps:// with 465 and smtp:// with 587. Also check for unencoded special characters in the password. Fondoo waits 10 seconds to connect and 30 seconds for the server to answer.
  • "SMTP did not accept the recipient": the server refused the address. This can be a typo, a blocked recipient, or a provider that only lets you send from approved addresses.
  • "Sender domain is not configured": the From domain is missing from domains, or is spelled differently.
  • "From must use the site's authenticated domain or the shared sending domain": check_sending_domain has not marked the domain verified. With SMTP, Fondoo has no DNS records of its own to check, so this check may not pass in the current release. This may differ for your account. If it stays false, contact Fondoo support.
  • Mail lands in spam: your provider's SPF and DKIM for the domain are missing or wrong. Fix them with your provider, then test again.

Limits, data and security

  • Fondoo sends through an SMTP connection at up to one message per second. Your provider may set lower hourly or daily limits.
  • Bounces that arrive later by email do not reach Fondoo, so Fondoo cannot suppress those addresses automatically. Watch your provider's bounce reports, and use a provider with webhooks (Resend, Postmark or SES) if automatic suppression matters to you.
  • Fondoo stores the URL, including the password, encrypted and bound to the connection. No operation returns it.
  • To rotate: create a new SMTP password, run configure_email_provider with the new URL, test, then revoke the old password.
  • To disconnect: set_provider({siteId, capability:"email", provider:"builtin"}), then revoke the SMTP user at your provider.
  • This is different from create_smtp_credentials. That operation creates login details for Fondoo's own SMTP endpoint, so your app can send mail through Fondoo. This guide is about Fondoo sending through your server.