API Reference

The Email binding is capability-only: it identifies the provisioned SES infrastructure, and your application talks to SES directly with the AWS SDK. There is no high-level Alien send API — workloads use @aws-sdk/client-sesv2 with the permissions granted through email/* permission sets.

The Binding

The binding is injected as JSON in the ALIEN_<ID>_BINDING environment variable (the resource id uppercased, hyphens replaced with underscores):

const binding = JSON.parse(process.env.ALIEN_MAILER_BINDING!)

The binding deliberately carries no domain list: identities are created and removed at runtime, so a list frozen at deploy time would be stale by design. Applications discover the current identities via ses:ListEmailIdentities (granted by email/manage-identities).

Permission Sets

Grant these through permission profiles:

.permissions({
  profiles: {
    execution: {
      mailer: ["email/send", "email/manage-identities"],
    },
  },
})

Because SES identities are named after customer mail domains — which are unknowable at deploy time — the identity permissions apply to all identities in the account and region, not just stack-prefixed ones. The configuration-set permissions stay stack-scoped.

Sending

Pass the binding's configuration set on every send:

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

const binding = JSON.parse(process.env.ALIEN_MAILER_BINDING!)
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." } },
    },
  },
}))

The workload's credentials come from its permission profile — no keys to configure.

Managing Identities at Runtime

With email/manage-identities, the application owns the domain lifecycle: create an identity when a customer adds a domain, hand them the DKIM records, poll verification, delete the identity when the domain is removed — all without an infrastructure change.

import {
  SESv2Client,
  CreateEmailIdentityCommand,
  GetEmailIdentityCommand,
  DeleteEmailIdentityCommand,
} from "@aws-sdk/client-sesv2"

const ses = new SESv2Client({ region: binding.region })

// Customer adds a domain
const created = await ses.send(new CreateEmailIdentityCommand({
  EmailIdentity: "mail.customer.com",
  ConfigurationSetName: binding.configurationSet,
}))
// created.DkimAttributes.Tokens — three DKIM tokens; the customer creates
// `<token>._domainkey.mail.customer.com CNAME <token>.dkim.amazonses.com`

// Poll verification
const identity = await ses.send(new GetEmailIdentityCommand({
  EmailIdentity: "mail.customer.com",
}))
// identity.VerifiedForSendingStatus

// Customer removes the domain
await ses.send(new DeleteEmailIdentityCommand({
  EmailIdentity: "mail.customer.com",
}))

Identities created this way are application data: they are not tracked by the deployment and survive stack deletion. Their lifecycle — including deletion — belongs to the application (see Behavior).

Inbound Mail

When .inbound(storage) is configured, raw incoming mail (full MIME messages) is written as objects into the linked Storage bucket. The receipt rule is a catch-all — mail for any identity the account receives mail for lands in the bucket, including identities verified at runtime. Read the objects with the Storage binding and parse them with a MIME library.

Activating the receipt rule set is a manual post-deploy step (see Behavior).

Sending Events

When .events(queue) is configured, SES publishes send, delivery, bounce, complaint, delivery-delay, and reject events for mail sent through the configuration set. Events flow through an SNS topic to the linked queue with raw message delivery, so each queue message body is the SES event JSON. Consume them with the Queue binding:

import { onQueueMessage } from "@alienplatform/sdk"

onQueueMessage("mail-events", async (message) => {
  const event = message.payload
  // event.eventType: "Send" | "Delivery" | "Bounce" | "Complaint" | ...
})