Amazon SES Setup

This guide walks you through setting up Amazon Simple Email Service (SES) as your email provider in CeramicCRM. After completing these steps, you will be able to send campaigns and transactional emails through your own verified domain.

Prerequisites

• An AWS account
• A domain you own (for sending emails)
• Access to your domain's DNS settings

Step 1: Verify Your Domain in Amazon SES

1. Open the Amazon SES Console
2. In the top-right corner, select the AWS Region closest to your users (e.g., Europe (Stockholm), US East (N. Virginia))
3. In the left sidebar, click Configuration → Identities
4. Click Create identity
5. Select Domain
6. Enter your domain name (e.g., yourdomain.com)
7. Under Advanced DKIM settings, keep Easy DKIM selected with RSA_2048_BIT signing length
8. Click Create identity

Add DNS Records

After creating the identity, AWS shows you DNS records to add:

1. DKIM records — Add all 3 CNAME records to your domain's DNS. These prove you own the domain and sign your emails.
2. SPF record — Add the TXT record for SPF validation. Without this, your emails may land in spam.

Wait for the Identity status to show Verified (usually takes a few minutes to a few hours depending on DNS propagation).

Step 2: Create an IAM User for CeramicCRM

IAM (Identity and Access Management) is a separate AWS service where you create credentials for CeramicCRM to send emails on your behalf.

1. Open the IAM Console (search "IAM" in the AWS services search bar)
2. In the left sidebar, click Users
3. Click Create user
4. Enter a user name: ceramiccrm-ses-sender
5. Do NOT check "Provide user access to the AWS Management Console" — this user is for API access only
6. Click Next

Attach SES Permissions

1. Select Attach policies directly
2. In the search box, type SES
3. Check the box next to AmazonSESFullAccess
   • Alternatively, for tighter security, click Create policy and use this JSON:

     {
       "Version": "2012-10-17",
       "Statement": [
         {
           "Effect": "Allow",
           "Action": [
             "ses:SendEmail",
             "ses:SendRawEmail"
           ],
           "Resource": "*"
         }
       ]
     }

4. Click Next
5. Click Create user

Generate Access Keys

1. Click on the newly created user name (ceramiccrm-ses-sender)
2. Click the Security credentials tab
3. Scroll down to Access keys
4. Click Create access key
5. Select Application running outside AWS
6. Click Next
7. Click Create access key
8. Important: Copy both the Access Key ID and Secret Access Key immediately. The secret key is shown only once — you cannot retrieve it later.

Save these credentials securely. You will need them in Step 4.

Step 3: Create a Configuration Set with SNS Webhook Tracking

A Configuration Set tells SES to notify CeramicCRM when emails are delivered, bounced, or marked as spam. Without this, your campaign analytics will not show delivery metrics. This step involves three AWS services: SES (configuration set), SNS (notification relay), and your CeramicCRM server (webhook receiver).

3.1 Create the Configuration Set in SES

1. Open the SES Console
2. Make sure you are in the same region as your verified domain (check the top-right region selector)
3. In the left sidebar, click Configuration → Configuration sets
4. Click Create set
5. Enter the name: ceramiccrm-tracking
6. Leave all other settings at their defaults:
   • Sending IP pool: default
   • Custom redirect domain: leave empty
   • Reputation metrics: enabled (recommended)
7. Click Create set

You now have an empty configuration set. Next, you need to tell it where to send event notifications.

3.2 Create an SNS Topic

Amazon SNS (Simple Notification Service) acts as the relay between SES and CeramicCRM. SES publishes events to an SNS topic, and SNS forwards them to your webhook URL.

1. Open the SNS Console (search "SNS" in the AWS services search bar)
2. Make sure you are in the same region as your SES configuration
3. In the left sidebar, click Topics
4. Click Create topic
5. Select Standard type (not FIFO)
6. Enter the name: ceramiccrm-ses-events
7. Expand Access policy and keep the default (only the topic owner can publish)
8. Click Create topic
9. Copy the Topic ARN shown at the top — you will need it in the next steps. It looks like: arn:aws:sns:eu-north-1:123456789012:ceramiccrm-ses-events

3.3 Create an SNS Subscription (Webhook to CeramicCRM)

This tells SNS to forward all messages to your CeramicCRM webhook endpoint.

1. On the topic page you just created, click Create subscription
2. The Topic ARN is pre-filled
3. For Protocol, select HTTPS
4. For Endpoint, enter your CeramicCRM webhook URL:

   https://your-ceramiccrm-domain.com/webhooks/email/ses

   Replace your-ceramiccrm-domain.com with your actual CeramicCRM server address.
5. Expand Subscription filter policy — leave empty (we want all events)
6. Check Enable raw message delivery — leave unchecked (CeramicCRM expects the standard SNS envelope)
7. Click Create subscription

3.4 Confirm the Subscription

When you create the subscription, SNS sends a confirmation request to your CeramicCRM webhook endpoint.

• If CeramicCRM is running and publicly accessible, it automatically confirms the subscription. The status changes from Pending confirmation to Confirmed within a few seconds.
• If the status stays Pending confirmation:
  1. Check that your CeramicCRM server is running and accessible from the internet
  2. Check that the URL is correct (no typos, includes /webhooks/email/ses)
  3. Check your server logs for the confirmation request
  4. You can click Request confirmation to resend

The subscription must show Confirmed before events will be delivered.

3.5 Add Event Destination to the Configuration Set

Now connect the SES Configuration Set to the SNS Topic.

1. Go back to the SES Console
2. Click Configuration → Configuration sets
3. Click on ceramiccrm-tracking
4. Click the Event destinations tab
5. Click Add destination
6. Select event types — check all of the following:
   • ✅ Sends — email accepted by SES
   • ✅ Deliveries — email delivered to recipient's mail server
   • ✅ Hard bounces — recipient address does not exist
   • ✅ Complaints — recipient marked email as spam
   • ✅ Rejects — SES rejected the email (e.g., virus detected)
   • ✅ Opens — recipient opened the email (requires tracking pixel)
   • ✅ Clicks — recipient clicked a tracked link
   • Optionally: Delivery delays, Rendering failures
7. Click Next
8. For Destination type, select Amazon SNS
9. For SNS topic, select ceramiccrm-ses-events (the topic you created in Step 3.2)
10. Enter a destination name: ceramiccrm-webhook
11. Click Next
12. Review the settings and click Add destination

3.6 Verify Events Are Flowing

To test that the full pipeline works:

1. In the SES Console, go to your verified identity (your domain)
2. Click Send test email (top right)
3. Fill in:
   • From: test@yourdomain.com
   • Scenario: Select "Custom"
   • Recipients: Enter a real email address you can check
   • Subject: "SES Webhook Test"
   • Body: "Testing event tracking"
   • Configuration set: Select ceramiccrm-tracking
4. Click Send test email
5. In CeramicCRM, navigate to Message Logs
6. You should see the email event appear within 30-60 seconds with status updates (sent → delivered)

If no events appear:

• Check that the SNS subscription status is Confirmed
• Check your CeramicCRM server logs for incoming webhook requests
• Verify you selected ceramiccrm-tracking as the configuration set when sending
• Ensure the SES region matches the SNS topic region

Architecture Summary

The event flow works like this:

SES sends email
    ↓
SES publishes event to Configuration Set
    ↓
Configuration Set routes to SNS Topic (ceramiccrm-ses-events)
    ↓
SNS forwards to HTTPS Subscription
    ↓
CeramicCRM webhook (/webhooks/email/ses) receives and processes event
    ↓
Event stored in ClickHouse → visible in Message Logs and Campaign Analytics

Step 4: Configure SES in CeramicCRM

Create a Channel

1. Log in to CeramicCRM

2. Navigate to Channels in the left sidebar

3. Click Create Channel

4. Fill in the channel details:

   • Name: Your channel name (e.g., "Production Email")
   • Type: Email
   • Provider: Amazon SES

5. In Provider Configuration, fill in:

   • Provider Type: Amazon SES
   • Use Case: Transactional or Marketing

6. In Amazon SES Configuration, enter:

7. In Sender Configuration, enter:

8. In Throttling (optional), set rate limits:

9. Click Create
10. Click Activate to enable the channel

Verify the Channel

1. On the channel detail page, click the Health Check button
2. A health status card appears showing:
   • Provider status (healthy/unhealthy)
   • Daily sending quota from SES
   • Emails sent today and remaining quota
   • Response latency
3. A green checkmark confirms the channel can connect to SES with your credentials

Verify Domain Ownership (CERAMICTXT)

After creating a channel with a Sending Domain, you will see a DNS Authentication panel with a CERAMICTXT record showing "Pending". This is CeramicCRM's own domain verification — separate from the SES verification you did in Step 1.

To verify:

1. On the channel detail page, find the DNS Authentication section
2. Note the record name and value shown (or click Verify to see them):
   • Record Type: TXT
   • Record Name: _ceramic.yourdomain.com
   • Record Value: pl-verify=<your-verification-token>
3. Go to your DNS provider (Cloudflare, Route 53, GoDaddy, Namecheap, etc.)
4. Add a new TXT record:

5. Wait for DNS propagation (usually a few minutes, can take up to 48 hours)
6. Return to CeramicCRM and click Verify
7. The status should change from "Pending" to "Verified"

You can copy the exact record name and value from the instructions panel in CeramicCRM — click "How to verify your domain" below the pending record for step-by-step guidance with copy buttons.

Step 5: Fix SPF Records

If you see a High recommendation in SES saying "SPF record not found for custom MAIL FROM domain":

1. In the SES Console, go to your verified identity
2. Scroll to Custom MAIL FROM domain
3. Click Edit
4. Enter a MAIL FROM subdomain (e.g., mail.yourdomain.com)
5. Add the MX and TXT (SPF) DNS records shown by AWS to your domain's DNS:
   • MX record: 10 feedback-smtp.{region}.amazonses.com
   • TXT record: v=spf1 include:amazonses.com ~all

Without SPF records, receiving mail servers may flag your emails as suspicious.

Step 6: Request Production Access

New SES accounts start in sandbox mode, which limits sending to verified email addresses only. To send to any recipient:

1. In the SES Console, click Account dashboard
2. Click Request production access
3. Fill in the form:
   • Mail type: Transactional or Marketing (or both)
   • Website URL: Your company website
   • Use case description: Describe how you will use email (e.g., "Customer engagement campaigns and transactional notifications via CeramicCRM")
4. Submit the request

AWS typically reviews and approves within 24 hours.

Available AWS Regions for SES

Choose the region closest to your recipients for the lowest latency.

Troubleshooting

"Access Denied" when sending

• Verify the IAM user has ses:SendEmail and ses:SendRawEmail permissions
• Confirm the Access Key ID and Secret Access Key are correct
• Check that credentials are for the correct AWS region

Emails going to spam

• Verify SPF records are configured (Step 5)
• Verify DKIM is set up and showing "Successful" in SES Console
• Make sure you have requested production access (Step 6)

"Email address is not verified"

• You are still in sandbox mode. Either verify the recipient address in SES, or request production access (Step 6)

Health check fails in CeramicCRM

• Double-check the region code matches where your domain is verified
• Verify the IAM user access keys are active (not deleted or deactivated)
• Check that the SES service is available in your chosen region