Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt

Use this file to discover all available pages before exploring further.

Production-grade email delivery using AWS Simple Email Service (SES) with bounce handling, suppression management, and observability.

​
Architecture

Truthlocks uses AWS SES for all transactional emails. The integration includes:
  • SES Provider: Direct integration with SES v2 API for sending emails
  • SNS Webhooks: Real-time bounce/complaint notifications via SNS topics
  • Suppression List: Automatic suppression of hard bounces and complaints
  • Environment Gating: Log-only mode for development, SES for production

​
AWS SES setup

​
1. Verify domain

Verify your sending domain in SES console: 
# Using AWS CLI
aws ses verify-domain-identity --domain truthlocks.com --region us-east-1

# Get DKIM tokens (add to DNS)
aws ses verify-domain-dkim --domain truthlocks.com --region us-east-1

​
2. Configure DNS records

Add the following records to your domain DNS:
TypeNameValue
TXT_amazonses.truthlocks.com(verification token from SES)
CNAME(DKIM selector 1)(DKIM value from SES)
MXmail.truthlocks.comfeedback-smtp.us-east-1.amazonses.com
TXTmail.truthlocks.comv=spf1 include:amazonses.com ~all

​
3. Request production access

New SES accounts are in sandbox mode. Request production access in the SES console to send emails to unverified addresses.

​
Environment variables

VariableRequiredDescription
EMAIL_MODEYeslog (dev) or ses (prod)
SES_REGIONIf sesAWS region (e.g., us-east-1)
SES_FROMIf sesSender address (e.g., no-reply@truthlocks.com)
SES_REPLY_TONoReply-to address for all outgoing emails
SES_CONFIGURATION_SETNoSES configuration set for tracking and reputation management
SES_WEBHOOK_SECRETNoSecret for validating SNS webhook signatures
EMAIL_CHECK_SUPPRESSIONNoWhen true, checks the suppression list before every send attempt
In ENV=production, the service will fail to start if SES_REGION and SES_FROM are not configured.

​
Bounce & complaint handling

SES notifications are received via an SNS webhook at /v1/notifications/ses-events.

​
Event types

  • Bounce (Permanent): Hard bounce — email suppressed automatically
  • Bounce (Transient): Soft bounce — logged but not suppressed
  • Complaint: User marked as spam — email suppressed automatically
  • Delivery: Successful delivery — logged for observability

​
Suppression list management

Suppressed emails are stored in the email_suppressions table and will not receive future emails. The API returns EMAIL_SUPPRESSED error code. 
-- Check if email is suppressed
SELECT * FROM email_suppressions WHERE email = 'user@example.com';

-- View recent suppressions
SELECT email, reason, suppressed_at
FROM email_suppressions
ORDER BY suppressed_at DESC
LIMIT 20;

​
Email sender management

You can manage sender identities and custom SMTP configuration from Settings > Email in the tenant console. This is useful when your organization requires emails to originate from your own domain or mail infrastructure.

​
Adding a sender

1

Open email settings

Navigate to Settings > Email in the tenant console.
2

Add a new sender

Click Add Sender and provide:
  • From email (required) — the address emails are sent from (e.g., noreply@agency.gov)
  • From name — display name shown to recipients
  • Reply-to — where replies are directed
3

Verify the sender

New senders start in PENDING status. Click Verify to trigger SES identity verification. Once SES confirms the domain, the sender moves to VERIFIED status.

​
Configuring custom SMTP

Enterprise and government tenants can bypass SES entirely by attaching a custom SMTP server to a verified sender. Once configured, all emails for that tenant route through your SMTP server.
1

Select a verified sender

In Settings > Email, choose a sender with VERIFIED or ACTIVE status.
2

Configure SMTP

Click Configure SMTP and provide:
  • SMTP host — your mail server hostname
  • SMTP port — typically 587 (STARTTLS) or 465 (TLS)
  • Username and Password — SMTP authentication credentials
  • Use TLS — enable for encrypted connections (recommended)
3

Send a test email

After saving, send a test email to confirm delivery. The sender status changes to ACTIVE once the first email is sent successfully.
Custom SMTP is particularly useful for government tenants that require emails to originate from their own mail infrastructure. See the B2G Procurement Pack for the full enterprise onboarding email flow.

​
Email template reference

Truthlocks uses named templates for all transactional emails. Each template supports placeholder substitution and is routed through either AWS SES or a tenant-configured custom SMTP server.

​
Onboarding & invitations

Template nameTriggerDescriptionPlaceholders
enterprise-onboarding-inviteGovernment tenant creation or lead qualificationBranded invite for enterprise/government administrators{{organization_name}}, {{invite_url}}
issuer-onboarding-inviteStandard tenant creationWelcome email for non-government issuers{{organization_name}}, {{invite_url}}
team-inviteTeam member invitationInvite for new team members within a tenant{{team_name}}, {{invite_url}}
verification-onboardingVerifier registrationOnboarding guide for verification partners{{organization_name}}, {{invite_url}}

​
Account & security

Template nameTriggerDescriptionPlaceholders
email-verificationAccount signupConfirms the user’s email address{{VERIFY_URL}}
password-resetPassword reset requestSecure password reset link{{reset_url}}
api-key-issuedAPI key creationConfirms a new API key was created for the account{{key_prefix}}, {{created_at}}
security-review-responseSecurity review completedNotifies the tenant of a security review outcome{{review_status}}, {{review_summary}}
incident-notificationSecurity incidentAlerts administrators to a platform security event{{incident_title}}, {{severity}}

​
Issuer lifecycle

Template nameTriggerDescriptionPlaceholders
issuer-approvedIssuer application approvedConfirms approval and shows the assigned trust tier{{assigned_tier}}, {{console_url}}
issuer-rejectedIssuer application rejectedNotifies the applicant with the rejection reason{{rejection_reason}}
issuer-evidence-requestAdditional evidence neededRequests compliance evidence for a trust tier application{{trust_tier_name}}, {{requested_evidence_description}}, {{upload_url}}

​
Enterprise onboarding sequence

Government and institutional tenants receive a sequence of lifecycle emails as they progress through onboarding. These are sent automatically at each stage.
Template nameStageDescription
invite_kickoffInvitationWelcome to Truthlocks Enterprise — links to the onboarding wizard
sandbox_readySandbox provisionedConfirms the sandbox environment is ready for integration testing
evidence_requestCompliance reviewRequests compliance documentation needed for production access
billing_activationBilling setupConfirms billing is active and the subscription plan is in place
webhooks_testIntegration testingConfirms webhook endpoints are configured and receiving test events
incident_notificationOngoingAlerts the tenant administrator to any platform incidents
approval_go_liveProduction approvedConfirms production access is granted and the tenant is live
The onboarding sequence is fully automated. As a platform admin, you trigger it by creating a tenant with the GOVERNMENT type or by qualifying a lead in the leads pipeline.

​
Other notifications

Template nameTriggerDescription
billing-upgrade-requiredUsage exceeds plan limitsPrompts the tenant to upgrade their billing plan
webhook-test-successWebhook test event deliveredConfirms a test webhook was delivered successfully
Government tenants (GOVERNMENT type) automatically receive the enterprise-onboarding-invite template instead of the standard issuer welcome. See the B2G Procurement Pack for details on the enterprise onboarding flow.

​
Troubleshooting

​
Email not received

  1. Check logs for email_sent or email_send_failed events
  2. Verify the recipient email is not in email_suppressions
  3. Check SES console for sending quota and reputation
  4. Verify DKIM/SPF records are correctly configured

​
Common error codes

Error codeMeaningResolution
EMAIL_SUPPRESSEDRecipient is on the suppression listRemove from email_suppressions if the issue is resolved
SES_ERRORAWS SES rejected the send requestCheck SES console for quota or configuration issues
CONFIG_ERRORMissing or invalid email configurationVerify environment variables are set correctly
INVALID_EMAILRecipient email address failed format validationConfirm the email address is valid

​
Observability

All email operations are logged with structured fields: 
{
  "level": "info",
  "msg": "email_sent",
  "message_id": "0102...",
  "to": "admin@agency.gov",
  "subject": "You've been invited to Truthlocks Enterprise",
  "template_name": "enterprise-onboarding-invite",
  "tenant_id": "tnt_abc123",
  "duration_ms": 245
}
Key log events to monitor:
EventLevelDescription
email_sentinfoEmail delivered to SES or SMTP successfully
email_send_failederrorEmail send attempt failed
email_suppressedwarnSend skipped because the recipient is suppressed
ses_webhook_receivedinfoSNS notification received from SES
ses_webhook_errorerrorFailed to process an SNS notification