Overview

alien.Email is email infrastructure for sending and receiving mail on your own domains. Declare it in your alien.ts and Alien provisions an SES configuration set, DKIM-verified domain identities, and optional inbound and event wiring — all in the customer's AWS account, so mail is sent with their domains and their sending reputation.

Platform Mapping

Email is currently available only on AWS.

When to Use

Use Email when your product sends or receives mail on customer-owned domains — transactional mail, notification delivery, or email-first products where each customer brings their own domain.

The resource owns the email infrastructure — the configuration set, event topology, and inbound topology — not the domain lifecycle. Products that create and verify domains dynamically (a customer adds a domain, your app hands them DNS records and polls verification) manage identities at runtime through the email/manage-identities grant instead of listing domains in the stack.

Stack Definition

const mailbox = new alien.Storage("mailbox").build()
const mailEvents = new alien.Queue("mail-events").build()

// Domain-dynamic products: no seed domains; identities are
// created at runtime through the email/manage-identities grant.
const email = new alien.Email("mailer")
  .inbound(mailbox)
  .events(mailEvents)
  .build()

// Static-domain products can seed identities at deploy time:
const seeded = new alien.Email("mailer")
  .domains(["mail.example.com"])
  .build()

domains may be empty — a configuration-set-only resource is valid. Adding a domain later provisions a new identity; removing one deletes its identity and DKIM verification state.

Domain Verification

Each domain gets an SES identity with Easy DKIM. The resource outputs carry three DKIM CNAME records per seed domain — create them in the domain's DNS, and SES verifies the domain asynchronously once they exist. For identities created at runtime, your application gets the DKIM tokens from the SES CreateEmailIdentity / GetEmailIdentity responses and hands them to the customer.

Sending

There is no high-level Alien send API. Workloads with the email/send grant send directly with the AWS SDK, passing the configuration set from the binding:

import { SESv2Client, SendEmailCommand } from "@aws-sdk/client-sesv2"

const binding = JSON.parse(process.env.ALIEN_MAILER_BINDING!)
// { service: "ses", region, configurationSet, eventTopicArn? }

const ses = new SESv2Client({ region: binding.region })
await ses.send(new SendEmailCommand({
  ConfigurationSetName: binding.configurationSet,
  FromEmailAddress: "hello@mail.example.com",
  Destination: { ToAddresses: ["someone@example.org"] },
  Content: {
    Simple: {
      Subject: { Data: "Hello" },
      Body: { Text: { Data: "Sent through Alien Email." } },
    },
  },
}))

See the API Reference for the binding fields, permission sets, and runtime identity management.