reCAPTCHA & Outbound Email

The public chat page has no login, so AVA protects it with Google reCAPTCHA
v3 (invisible scoring — clients never solve a puzzle) plus server-side rate
limiting. Outbound transactional email goes through SMTP2GO. This page
covers both setups and the fail-closed rules that govern them.

---

Google reCAPTCHA v3

Create the site

At the Google reCAPTCHA admin console,
create a v3 site for your public chat hostname (e.g. chat.example.com).
Add localhost to the site's domains if you also want local development to
verify against the real service. Collect the two keys:

How verification behaves

• Every chat-start (and the email-fallback form) submission carries a
  reCAPTCHA token that the server verifies against Google's siteverify
  endpoint before doing anything else.
• Verification is score-based and rejects low-scoring (bot-like) tokens,
  tokens minted for a different action, and tokens minted on a different
  hostname.
• The outbound call to Google has its own timeout (RECAPTCHA_TIMEOUT_MS,
  default 10000 ms), so a hung Google endpoint cannot stall requests.
• Verification is fail-closed: a missing secret, a network error reaching
  Google, or an explicit failure from Google all reject the request. A Google
  outage cannot silently disable bot protection.

RECAPTCHA_DEV_BYPASS — development only, refused in production

For local development or CI where you don't want to configure real keys:

Two hard properties worth knowing:

• It is refused outright in production. When NODE_ENV=production, the
  bypass is ignored no matter what the variable says — no runtime
  configuration can disable bot protection on a production deployment.
• The match is exact: 1, yes, TRUE etc. do not activate it.

Since local development typically has a real RECAPTCHA_SECRET_KEY anyway
(with localhost on the site's domain list), most deployments never need this
variable at all.

---

SMTP2GO — outbound email

AVA sends three kinds of transactional mail:

Account setup

Create an SMTP2GO account and an SMTP user under it (Settings → SMTP
Users), and verify your sending domain so mail from your SMTP2GO_FROM
address passes SPF/DKIM. Then set:

SMTP2GO_FROM is fail-closed. There is no built-in sender address: if
SMTP2GO_FROM is unset or empty, every email route refuses to send — the
attempt is logged as an error and the request returns a clean failure
instead of mailing from a made-up address. Set it to an address on a domain
your SMTP2GO account is authorized to send from.

While the SMTP transport is SMTP2GO-shaped by default, the host/port/user/
password are plain SMTP settings — another SMTP relay that accepts
username/password auth on these variables will also work.

Recipient configuration (fail-closed contract)

None of the recipient addresses have built-in defaults — a deployment can
never silently send mail to an address you didn't configure:

SUPPORT_FALLBACK_EMAIL is boot-required because it backs a client-facing
promise: when chat is unavailable, the "email us a ticket" form must actually
deliver somewhere. The other two are internal conveniences and simply stay off
until you configure them.

---

Environment variable summary

See configuration.md for the complete configuration
reference.

---

Next steps

• quickstart.md — these values are set in the credential
  step of the bring-up.
• white-label.md — the rest of the deployment identity
  (company name, phone, portal link) that appears alongside these email
  touchpoints.