Sending email

Choose the email provider #

Korenact supports plain-text outbound follow-ups through Resend or authenticated SMTP. The server operator installs credentials in the repository root .env; the client selects the provider in Connections → Messages. These are outgoing agent actions, not a general inbound email inbox. Configuring them does not add password reset or signup-verification emails.

The migration, API, and webhook worker receive the root environment. Browser VITE_* variables and documentation HTML must never contain API keys or SMTP passwords. A blank email credential reference uses the server defaults; an explicit reference uses only that organization's secret.

Resend: server setup #

1. Create the sending domain in Resend and complete its requested DNS verification.
2. Create a full-access API key for this integration. Korenact checks GET /domains before connecting, so a send-only key cannot perform this verification.
3. Edit the existing root .env on the deployment server. Fill in the settings below with your real key and a sender on the verified domain.
4. Recreate the backend containers after editing the environment. A restart alone keeps the old container environment.

EMAIL_PROVIDER=resend
EMAIL_FROM_ADDRESS=notifications@korenact.com
EMAIL_FROM_NAME=Korenact
EMAIL_REPLY_TO=support@korenact.com
EMAIL_TIMEOUT_SECONDS=10
RESEND_API_KEY=YOUR_REAL_RESEND_KEY

docker compose up -d --no-deps --force-recreate api webhook-worker frontend edge

Run this from the repository root after confirming the database matches the deployed release. Recreating frontend and edge refreshes their upstream addresses after API replacement and can briefly interrupt public traffic.

Use your own sender and reply address if operating a different domain. Connection verification checks the exact sender domain and sending capability. Email sends use the action ID as Resend's idempotency key. See Resend's domain API and sending API.

SMTP: server setup #

1. Obtain your provider's SMTP host, port, username, and SMTP or app password.
2. Use a sender address the provider permits. Configure the provider's required domain authentication.
3. Set the root environment as below. Port 587 uses STARTTLS. For implicit TLS on port 465, set SMTP_USE_TLS=false and SMTP_USE_SSL=true.
4. Recreate API and webhook-worker containers, then connect SMTP in the workspace.

EMAIL_PROVIDER=smtp
EMAIL_FROM_ADDRESS=notifications@korenact.com
EMAIL_FROM_NAME=Korenact
EMAIL_REPLY_TO=support@korenact.com
EMAIL_TIMEOUT_SECONDS=10
SMTP_HOST=YOUR_PROVIDER_SMTP_HOST
SMTP_PORT=587
SMTP_USERNAME=YOUR_SMTP_USERNAME
SMTP_PASSWORD=YOUR_SMTP_PASSWORD
SMTP_USE_TLS=true
SMTP_USE_SSL=false

Exactly one TLS mode must be enabled. Certificate verification remains enabled. Korenact checks TLS and authentication without sending a test email. SMTP server acceptance is not proof of inbox delivery; monitor your provider's delivery records. SMTP does not supply the Resend API's idempotency guarantee, so an uncertain write is held for staff review and never automatically resent.

Give a client its own sender #

For a client's own email account, use a tenant secret instead of changing global defaults. Read the client's organization ID from the signed-in organization API response. Uppercase the actual ID and the reference name. For reference client_email, add this root environment variable using the real organization ID:

# Replace ORG_ID_UPPER with the actual uppercased organization ID.
KORENACT_INTEGRATION_ORG_ID_UPPER_CLIENT_EMAIL='{"api_key":"YOUR_KEY","from_address":"notifications@client-domain.com","from_name":"Client services","reply_to":"support@client-domain.com"}'

For SMTP, the JSON object uses host, port, username, password, use_tls, use_ssl, from_address, from_name, and optional reply_to. Use JSON booleans, not quoted strings. The tenant reference must not point to another organization's environment variable.

Connect and enable email in the workspace #

1. Open Connections, choose System Messages, then Provider Resend email or SMTP email.
2. Enter a display name.
3. Leave Credential reference blank for the server's Korenact defaults, or enter client_email for the tenant secret.
4. Select Connect. Confirm Verified connection; resolve verification errors before proceeding.
5. Open the responsible agent. Under Requests and actions, enable Document request and Send an email if that is the intended workflow.
6. Open the attached rules. Permit message.send_email, grant contact.basic, and configure identity checks or staff approval appropriate to the contents.
7. Test with a controlled recipient. Provide a valid email address, subject, and body as requested. The provider supports plain text; attachments and automatic document generation are not supplied by these adapters.
8. Review the action confirmation and your provider's delivery logs.

One provider connection is allowed per system kind. If Messages already uses another provider, coordinate disconnecting it before selecting email. Live Telnyx call transfers and replies to inbound SMS continue through the telephony gateway, rather than this outbound-email adapter.

Understand email outcomes #

An executed email action means the provider accepted the message and returned a reference. It does not guarantee inbox placement or delivery. A rejection is shown as failed. A timeout after a possible send is shown as Outcome unknown; staff must inspect provider records before creating another request. Credentials and raw provider errors are not shown to callers or stored in the action result.