Fondoo
GitHubStart your 7-day trial for $0Start trial
Docs

Connect Amazon SES to Fondoo

Live6 min readUpdated

This guide sets your own Amazon Simple Email Service (SES) account as the delivery service for your Fondoo site. Fondoo uses your AWS keys to set up the sending domain in SES and to send each message. It reads delivery, bounce and complaint events back through Amazon SNS. Your AI agent keeps using the normal Fondoo email operations, such as sendemail, while AWS bills you for the sending.

What Fondoo can do with it

With your keys, Fondoo will:

  • Create a configuration set in your SES account named fondoo-<your workspace ID>. It adds an event destination called fondoo that publishes Send, Delivery, Bounce, Complaint, Open and Click events to your SNS topic.
  • Create the domain identity in SES with Easy DKIM (2048-bit). It also sets a custom MAIL FROM subdomain (default fondoo-mail.<your domain>) that rejects mail if its MX record is missing.
  • Return the exact DNS records to add: three DKIM CNAMEs, an MX and SPF TXT record for the MAIL FROM subdomain, and a DMARC record. If you already have a DMARC record, Fondoo keeps it.
  • Read your SES sending quota and pause when your 24-hour limit or send rate is reached.
  • Send each message with the configuration set, tagged with Fondoo's delivery ID.
  • Suppress addresses that hard bounce or complain.

Approvals and limits that still apply:

  • configure_email_provider and set_provider need the workspace owner.
  • Marketing email needs evidenced consent and a postal address set with update_email_settings.
  • An agent that sends more than 1,000 marketing emails for a site in a month needs your approval.

Before you start

  • An AWS account, and the AWS Region you will send from, for example us-east-1. SES, the domain identity and the SNS topic must all be in that Region.
  • Production access in that Region. New SES accounts start in the sandbox. There you can only send to verified addresses, up to 200 messages per 24 hours, at 1 message per second. Sandbox status is separate in each Region (request production access).
  • Cost: SES à la carte pricing is $0.10 per 1,000 emails, plus $0.12 per GB of attachments. SNS notifications are charged at standard SNS rates (SES pricing). Fondoo's per-site email overage charge does not apply to mail sent through your own provider.
  • Your domain added and verified on your Fondoo site (set_custom_domain, then get_domain_status until it is active).
  • Access to your domain's DNS.

Step by step: get your credentials

  1. Create the SNS topic. Open the SNS console in your sending Region and choose Topics → Create topic. Choose type Standard, because SES does not support FIFO topics. Copy the topic ARN, for example arn:aws:sns:us-east-1:111122223333:fondoo-email.
  2. Let SES publish to it. Open the topic, choose Edit, expand Access policy, and add a statement like the one below. It is AWS's own example, with the source narrowed to Fondoo's configuration sets (SNS event destination). If the topic uses KMS encryption, also give ses.amazonaws.com kms:GenerateDataKey and kms:Decrypt on the key (SNS notifications).
    {
  "Effect": "Allow",
  "Principal": { "Service": "ses.amazonaws.com" },
  "Action": "sns:Publish",
  "Resource": "arn:aws:sns:REGION:ACCOUNT_ID:TOPIC_NAME",
  "Condition": {
    "StringEquals": { "AWS:SourceAccount": "ACCOUNT_ID" },
    "ArnLike": { "AWS:SourceArn": "arn:aws:ses:REGION:ACCOUNT_ID:configuration-set/fondoo-*" }
  }
}
  3. Create an IAM user for Fondoo. In the IAM console choose Users → Create user and give it a name like fondoo-ses. Do not use your root account. Attach a policy that allows only what Fondoo calls:
    {
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "ses:SendEmail",
      "ses:GetAccount",
      "ses:CreateEmailIdentity",
      "ses:GetEmailIdentity",
      "ses:PutEmailIdentityMailFromAttributes",
      "ses:CreateConfigurationSet",
      "ses:CreateConfigurationSetEventDestination"
    ],
    "Resource": "*"
  }]
}
    You can narrow Resource to your identity and configuration set ARNs later.
  4. Create an access key. Open the user, choose Security credentials → Create access key, and copy the access key ID and secret access key. AWS shows the secret only once (access keys). These are AWS API keys. SES SMTP credentials will not work here.
  5. Request production access. In the SES console open Account dashboard → View Get set up page → Request production access. AWS gives an initial response within 96 hours.

You now have:

Fondoo credential fieldWhat to put in it
region (required)Your SES Region, for example us-east-1
accessKeyId (required)From step 4
secretAccessKey (required)From step 4
topicArn (required)From step 1

Connect it in Fondoo

In the dashboard. The Connections page lists an Email card, but it only opens setup instructions. There is no form for SES keys yet. Use your agent or the REST API.

By asking your agent. Example prompt:

Use my Amazon SES account for this site's email. I have saved the keys. Set up example.com as the sending domain and give me the DNS records.

configure_email_provider takes the secret key directly in its input and has no secure paste page. Anything pasted into a chat can stay in chat logs, so run that call yourself over REST with an owner API key.

The calls, in order:

  1. configure_email_provider({siteId, provider:"ses", credential:{region, accessKeyId, secretAccessKey, topicArn}}). Leave out siteId for the workspace default.
  2. set_provider({siteId, capability:"email", provider:"ses"}).
  3. setup_sending_domain({siteId, domain:"example.com"}). Add mailFromLabel to use a subdomain other than fondoo-mail. The response lists the DNS records and configurationSet. If Fondoo manages your DNS zone, it applies them for you (applied: true).
  4. Add the records at your DNS host, then run check_sending_domain({siteId, domain}).

REST equivalent:

curl -X POST https://api.getfondoo.com/v1/ops/configure_email_provider \
  -H "Authorization: Bearer $FONDOO_OWNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"YOUR-SITE-ID","provider":"ses","credential":{"region":"us-east-1","accessKeyId":"'"$AWS_KEY_ID"'","secretAccessKey":"'"$AWS_SECRET"'","topicArn":"arn:aws:sns:us-east-1:111122223333:fondoo-email"}}'

Webhooks

SES events reach Fondoo through your SNS topic.

  1. Run get_email_provider({siteId}) and copy feedbackUrl (.../webhooks/email/ses/<providerId>).
  2. In the SNS console choose Subscriptions → Create subscription. Pick your topic, set Protocol to HTTPS, paste the URL as Endpoint, and leave raw message delivery off (create a subscription).
  3. SNS sends a confirmation request to the endpoint. Fondoo's per-connection SES endpoint does not confirm it automatically, and expects the subscription to be confirmed in AWS. If the subscription stays Pending confirmation, this may differ for your account. Ask Fondoo support to complete it.

How signing works: Fondoo checks each SNS message signature against Amazon's signing certificate. It accepts only your configured topicArn. It also checks that the event carries your fondoo-<workspace ID> configuration set and that the recipient matches the original delivery.

Test that it works

  1. check_sending_domain({siteId, domain}) returns verified: true once SES reports the domain verified, DKIM SUCCESS and MAIL FROM SUCCESS, and the DNS records resolve.
  2. Add yourself as a contact (create_contact) and send a transactional message with send_email({..., category:"transactional"}). While in the sandbox, the recipient must be verified in SES.
  3. Check list_emails({siteId}). Once SNS is confirmed, delivery events update the status.

Troubleshooting

  • AccessDenied in the delivery log or on setup: the IAM policy is missing an action from step 3, or the keys belong to another user.
  • Stuck at verified: false: DNS has not propagated, the MAIL FROM MX record is missing, or there are two SPF records on the MAIL FROM name. Fondoo merges SPF where it can and reports multipleSpf.
  • "MAIL FROM subdomain already has MX records; choose an unused subdomain.": pass a different mailFromLabel.
  • Sends paused as rate limited: you are in the sandbox, or at your 24-hour quota. Request production access or a quota increase.
  • InvalidParameterValue when the event destination is created: the SNS topic is FIFO, in another Region, or KMS-encrypted without the key policy.
  • "Invalid SNS signature or topic": the subscription points at a different topic than topicArn, or raw message delivery is on.

Limits, data and security

  • Sending speed follows your SES quota (GetAccount). The Fondoo operator's own pacing applies as a cap.
  • Fondoo stores the four credential values encrypted, bound to the connection. No operation returns them.
  • Fondoo stores delivery records, DNS records it generated, and suppression entries. From events it uses only the type, message ID, recipient and bounce type.
  • To rotate: create a second access key, run configure_email_provider with it, test, then deactivate and delete the old key in IAM.
  • To disconnect: set_provider({siteId, capability:"email", provider:"builtin"}). Then delete the IAM key. Optionally remove the fondoo-* configuration set and the SNS subscription.