Skip to main content

Troubleshooting

Common issues and their solutions when working with The One Relay.

1. Email Not Delivered​

Symptoms: Email shows sent status in logs but never reaches delivered.

Steps:

  1. Check Email Logs — look for the specific email and its status
  2. If status is bounced, check the bounce type and sub-type for details
  3. If status stays at sent, the delivery event from SES may not have arrived yet — wait 5 minutes and refresh
  4. Check if the recipient's domain has valid MX records: dig MX example.com
  5. Check the recipient's spam/junk folder

Common causes:

  • Recipient address doesn't exist (hard bounce)
  • Recipient's mailbox is full (soft bounce — SES retries)
  • Your domain is blacklisted by the recipient's mail server
  • SES delivery events not reaching Relay (SNS subscription issue)

2. Domain Verification Failing​

Symptoms: Domain stuck in Pending status after adding DNS records.

Steps:

  1. Open the domain and review the DNS records dialog
  2. Verify each record exists in your DNS provider exactly as shown
  3. Check for typos in CNAME names and values
  4. Confirm you don't have duplicate SPF records (only one TXT record with v=spf1 is allowed)
  5. Wait up to 48 hours for DNS propagation, then click Verify again

Common causes:

  • DNS records not yet propagated (TTL-dependent)
  • Incorrect CNAME target (copied wrong value)
  • Multiple SPF records on the domain (merge into one)
  • DNS provider added extra dots or quotes to record values

3. API Key Returns 401 Unauthorized​

Symptoms: API requests return 401 Unauthorized.

Steps:

  1. Verify the key is in the X-Relay-Key header (not Authorization)
  2. Check the key hasn't been revoked — look on the API Keys page
  3. Check the key hasn't expired — compare expiration date to current date
  4. Verify you're using the full key, not just the masked preview
  5. Confirm you're hitting the correct API URL (api.theonerelay.app)

4. API Key Returns 403 Forbidden​

Symptoms: API requests return 403 Forbidden even with a valid key.

Steps:

  1. The key is valid but lacks the required scope for this endpoint
  2. Check the key's scopes on the API Keys page
  3. Add the missing scope (e.g., send for /api/send, read-logs for /api/logs)
  4. Or create a new key with the correct scopes

5. Rate Limited (429 Too Many Requests)​

Symptoms: Send requests return 429 with a Retry-After header.

Steps:

  1. Check which rate limit window you're hitting — the error response includes details
  2. Implement retry logic that respects the Retry-After header
  3. If hitting per-second limits, add delays between sends
  4. For batch operations, spread sends over time rather than sending all at once
  5. Consider increasing rate limits in Settings if your volume is legitimate

Common causes:

  • Sending too many emails in a short burst
  • Batch job not pacing sends properly
  • Multiple integrations sending simultaneously

6. High Bounce Rate Alert​

Symptoms: Receiving bounce rate alert emails or seeing warnings in Analytics.

Steps:

  1. Open Analytics and check the Bounce Rate Trend
  2. Open Email Logs and filter by status bounced to see which addresses are bouncing
  3. Check if bounces are concentrated on specific domains (could indicate a blocklist)
  4. Review the Suppression List — addresses should be auto-suppressed after hard bounces
  5. Clean your recipient lists by removing addresses that haven't engaged recently

Common causes:

  • Sending to an old or unvalidated contact list
  • Client's email server is rejecting your domain (check blocklists)
  • DNS authentication records (SPF/DKIM/DMARC) were modified or removed

7. Inbound Emails Not Routing​

Symptoms: Emails sent to [email protected] (or similar) don't appear in PSA/CRM/Portal.

Steps:

  1. Check the inbound_emails container in Cosmos — verify the email was received
  2. If not received, check SES receipt rules and S3 bucket for the raw email
  3. If received but not routed, check integration environment variables: PSA_API_URL, CRM_API_URL, PORTAL_API_URL, INTEGRATION_KEY
  4. Check the destination API is running and accessible
  5. Check for routing pattern mismatches (e.g., ticket+abc where abc isn't a valid ticket ID)

Common causes:

  • Integration environment variables not set on Relay function app
  • Destination product API is down or unreachable
  • SNS subscription for inbound emails not confirmed
  • SES receipt rule not active

8. Template Variables Not Replaced​

Symptoms: Emails contain literal {{variable_name}} text instead of values.

Steps:

  1. Verify the variable names in your template match the keys in your variables object (case-sensitive)
  2. Check for typos: {{client_name}} in template must match "client_name" in the send request
  3. Use the Test Send feature to preview variable substitution before production use
  4. Check that you're using the template send endpoint (/api/send-template), not the regular send endpoint

9. Open/Click Tracking Not Working​

Symptoms: Analytics show 0% open rate despite confirmed email delivery.

Steps:

  1. Open tracking requires images to load — many email clients block images by default
  2. Check if the recipient's email client blocks external images (Outlook, corporate mail filters)
  3. Click tracking requires link rewriting — verify your HTML includes <a href> links
  4. Check that the SES configuration set has open and click tracking enabled
  5. Some open rates below 20% are normal for transactional email
ℹ️Open tracking undercounts by design. It relies on a tracking pixel that many email clients block. Click tracking is more reliable as an engagement metric.

10. Emails Going to Spam​

Symptoms: Delivered emails land in recipient's spam/junk folder instead of inbox.

Steps:

  1. Verify all DNS records are properly configured: SPF, DKIM, and DMARC
  2. Check your domain against blocklists at MXToolbox
  3. Review your bounce and complaint rates in Analytics — high rates damage sender reputation
  4. Ensure email content doesn't trigger spam filters:
    • Avoid ALL CAPS in subject lines
    • Don't use excessive exclamation marks
    • Include a plain text version alongside HTML
    • Maintain a reasonable text-to-image ratio
  5. Build sender reputation gradually by starting with low volume and increasing over time

11. CSV Export Empty or Incomplete​

Symptoms: Export downloads but contains fewer records than expected.

Steps:

  1. Check your active filters — exports respect the current filter state
  2. Clear all filters to export the complete dataset
  3. For large exports, use date range filters to break into smaller chunks
  4. Check that logs exist for the selected date range in the Email Logs view

12. SES Webhook Events Not Processing​

Symptoms: Email logs stay at sent status and never update to delivered/bounced.

Steps:

  1. Verify the SNS topic subscription is confirmed and active
  2. Check that the webhook endpoint (/api/webhooks/ses) is accessible from the internet
  3. Verify the SES configuration set theonerelay-events is assigned to your SES identity
  4. Check Relay function app logs for webhook processing errors
  5. Test by sending an email and checking SES sending statistics in the AWS console — if SES shows delivery but Relay doesn't, the webhook pipeline is broken

When to Contact Support​

Contact support if:

  • Your SES account is suspended or under review
  • Domain verification has failed for more than 48 hours with correct DNS records
  • Webhook events stop processing for all tenants (platform-wide issue)
  • You need rate limit increases beyond standard tiers
  • Inbound routing is silently dropping emails (not stored in inbound archive either)

For all other issues, the steps above should resolve the problem. Check Email Logs and Analytics first — they contain the data needed to diagnose most issues.