Email Integration — Setup Guide
VocaLoop sends emails (your email template with the project fill link) through system credentials: the server's Amazon SES account, falling back to its SMTP configuration when SES is not set up. There is nothing to paste in — you switch the channel on and send. Bringing your own SMTP or SES credentials is coming soon.
Looking for another channel? See the WhatsApp or Twilio SMS guides, or the Channel Setup overview.
Step 1 — Enable the channel
Open Settings → Integrations.
On the Email card, switch Enabled on. Email is off for new accounts; WhatsApp is the only channel on by default.
The card shows the sender the messages will come from — VocaLoop's system sender address and name.
Step 2 — Verify with a test send
On the Email card, enter your own address and click the test send. A real message goes out through the system credentials; the provider's answer is shown verbatim, so a bounce or a rejected sender is visible immediately.
You can also send a test from a project's Templates tab — the email template's test send uses the same credentials, and the fill page it links to carries a test-only notice.
What recipients see
From — the system sender (
SES_SENDER_NAME <SES_SENDER_EMAIL>or the SMTP equivalent). Replies go to that address, not to you.Subject and body — the project's email template (or the account default, or the stock message). See Sending & Tracking for the template hierarchy and the
{link},{project},{company}placeholders.The fill link — always present; appended automatically if the template omits
{link}.
Server configuration (self-hosted)
The email channel's system credentials are the same ones VocaLoop uses for its own lifecycle mail (verification links, password resets). Set them in the root .env; SES is preferred, SMTP is the fallback when the SES block is empty.
Amazon SES
| Variable | Notes |
|---|---|
AWS_SES_ACCESS_KEY_ID, AWS_SES_SECRET_ACCESS_KEY | An IAM user allowed to call ses:SendRawEmail |
AWS_SES_REGION | Region of the verified identity, default us-east-1 |
SES_SENDER_EMAIL, SES_SENDER_NAME | The verified sender identity and its display name |
New SES accounts start in sandbox mode and can only send to verified addresses — request production access before real recipients.
SMTP fallback
| Variable | Notes |
|---|---|
SMTP_HOST, SMTP_PORT | Port 587 (STARTTLS, the default) or 465 (implicit TLS) |
SMTP_USERNAME, SMTP_PASSWORD | The SMTP login |
SMTP_FROM_EMAIL, SMTP_FROM_NAME | The sender recipients see; must be allowed by the provider |
SMTP_USE_TLS | Leave true for port 587 |
Provider notes:
Gmail / Google Workspace — regular passwords won't work. Create an App password (Google Account → Security → 2-Step Verification → App passwords) and use it as the SMTP password with host
smtp.gmail.com, port587, username = your full address.SendGrid — username is literally
apikey; password is an API key with Mail Send permission; the From address must be a verified sender.Amazon SES over SMTP — use SMTP credentials (not your AWS keys) from the SES console and verify the From domain/address first.
The Admin → Credentials page shows which of the two is in effect and whether the SMTP block is complete.
Troubleshooting
| Symptom | What to check |
|---|---|
| Test send fails with "channel is disabled" | Switch the Email card on first |
"not configured" / 503 | Neither the SES block nor the SMTP block is complete on the server |
SES MessageRejected / address not verified | The sender identity isn't verified, or the account is still in the SES sandbox and the recipient isn't verified |
| SMTP authentication failed | Wrong app password / API key, or the provider blocks the login until access is enabled |
| The mail lands in spam | Set up SPF and DKIM for the sender domain at your provider |
Security notes
Credentials live only in the server's
.env; they are never shown in the app beyond a masked indicator on the Admin page.Recipients see the system sender, so keep its mailbox monitored or route replies elsewhere at the provider.