HerdOS Reset Email Setup

Why reset emails may not arrive
- The browser-only HerdOS demo can create a local reset code, but it cannot send email by itself.
- Real reset emails require the HerdOS API to be running and connected to an email provider.
- The API reads email provider settings only from server-side environment variables such as .env or cloud platform secrets.

Required production setup
1. Choose an email provider that supports SMTP or webhooks.
   Common options include Google Workspace app passwords, SendGrid SMTP, Mailgun SMTP, Amazon SES SMTP, Postmark SMTP, or a custom email webhook.

2. Add SMTP settings to the root .env file or to your cloud host secrets:

HERDOS_SMTP_HOST=smtp.your-email-provider.com
HERDOS_SMTP_PORT=587
HERDOS_SMTP_SECURE=false
HERDOS_SMTP_USER=your-smtp-username-or-api-key
HERDOS_SMTP_PASS=your-smtp-password-or-api-secret
HERDOS_PASSWORD_RESET_EMAIL_FROM="HerdOS Support <support@your-domain.com>"
HERDOS_PASSWORD_RESET_REPLY_TO=support@your-domain.com

3. Make sure the API dependencies are installed:

cd outputs/api
npm install

4. Restart the HerdOS API after changing .env or cloud secrets.

5. Confirm the Main platform is connected to the API through the Cloud / Offline Sync settings. If the platform is not connected to the API, it will only create a local reset code on the current device.

Webhook alternative
- Instead of SMTP, configure:

HERDOS_PASSWORD_RESET_WEBHOOK_URL=https://your-email-provider.example/herdos-password-reset
HERDOS_PASSWORD_RESET_WEBHOOK_TOKEN=replace-with-server-side-email-webhook-secret

- HerdOS will POST JSON to that URL with these important fields:

schema: HerdOS-Password-Reset-Webhook-v1
eventType: password_reset.requested
organizationId: the farm account ID
herdosId: the client-facing HerdOS ID
to: the registered owner or manager email
subject: the reset email subject
resetLink: the one-time reset link to send to the client
resetCode: the same one-time code for providers that cannot format links
expiresAt: when the reset expires
email.text: a ready-to-send plain text email
email.html: a ready-to-send HTML email

- HerdOS also sends these headers to help your email automation verify and deduplicate requests:

Authorization: Bearer <HERDOS_PASSWORD_RESET_WEBHOOK_TOKEN>
X-HerdOS-Webhook-Topic: password_reset.requested
X-HerdOS-Organization-Id: the farm account ID
X-HerdOS-Webhook-Event-Id: stable reset event ID
X-HerdOS-Idempotency-Key: stable reset event ID
X-HerdOS-Webhook-Timestamp: reset request time

Security notes
- Never place SMTP passwords, webhook tokens, or API keys inside frontend JavaScript, HTML, or mobile app files.
- Do not reveal old passwords to owners, managers, or administrators. Reset them with a short-lived token.
- In production, set HERDOS_RETURN_RESET_TOKEN=false so reset codes are delivered only through the configured email provider.
