Troubleshooting

Common issues and how to resolve them.

Emails not arriving

1. Check DNS records: verify MX and TXT records are correctly set:

   dig MX receive.yourdomain.com
   dig TXT _amazonses.receive.yourdomain.com

2. Check SES verification: confirm your domain shows as Verified in the SES Console.
3. Check the region: SES inbound only works in us-east-1, us-west-2, and eu-west-1.
4. Check the S3 bucket: look for .eml files under the incoming/ prefix in the AWS Console.
5. Check Ingest Lambda logs: CloudWatch logs will show parsing errors if the email couldn't be processed.

API returns empty results

1. Check the inbox name: it's the local part of the email address (before @), case-insensitive. If you sent to Test@receive.yourdomain.com, query inbox=test.
2. Wait for processing: there's a small delay (typically under 2 seconds) between email arrival and API availability.
3. Use long-polling: add wait=true to block until emails arrive:

   curl -H "Authorization: Bearer $TOKEN" \
     "$API_URL/v1/emails?inbox=test&wait=true&timeout=15"

Deploy fails

1. Wrong AWS region: must be us-east-1, us-west-2, or eu-west-1.
2. Invalid credentials: ensure your AWS_PROFILE has permissions for Lambda, S3, DynamoDB, SES, and CloudFormation.
3. SES receipt rule conflict: only one active receipt rule set per region per account. Deactivate any existing rule set first.

reading ACM Certificates: empty result

The ACM certificate lookup failed. This happens when API_DOMAIN is set without HOSTED_ZONE_ID and no matching certificate exists.

Verify:

1. The certificate domain matches API_DOMAIN exactly
2. The certificate is in the same region as AWS_REGION
3. The certificate status is Issued (not Pending Validation)

aws acm list-certificates --region $AWS_REGION \
  --query "CertificateSummaryList[?DomainName=='api.inbox.yourdomain.com']"

Deploy hangs on deleting ApiRouterCdnSslCertificate

This can happen when switching from Route 53 to external DNS. CloudFront may hold onto the certificate SST is trying to delete.

If the delete hangs for more than 5 minutes, use --target to remove only the specific resource that's stuck instead of tearing down the entire stack:

bun x sst remove --stage dev --target ApiRouter

This removes the CloudFront distribution and its associated certificate without affecting your S3 bucket, DynamoDB tables, or SES configuration. Then redeploy to recreate it cleanly.

Authentication errors

• 401 UNAUTHORIZED: check that you're sending the token in the Authorization header as Bearer <token>.
• Token not working: tokens are stored as SHA-256 hashes. If you lost the original token, revoke the key and create a new one:

  bun run provision --list         # find the keyId
  bun run provision --revoke <keyId>
  bun run provision --create --name new-key

FAQ

Can I use a root domain instead of a subdomain?

You can, but it's not recommended. Using receive.yourdomain.com avoids conflicts with existing MX records on your root domain.

How long are emails stored?

All data auto-expires. See Data Retention for the full breakdown and how to customize retention periods.

Is there a rate limit?

No application-level rate limits. AWS Lambda concurrency limits apply (default: 1000 concurrent executions per region).

Can multiple projects share the same deployment?

Yes, that's the intended setup. Deploy once, create separate API keys per project, and use unique inbox prefixes to isolate emails.