AWS.MailManager reference

AddonInstance

Source: src/AWS/MailManager/AddonInstance.ts

An SES Mail Manager Add On instance — a usable deployment of a subscribed Add On that rule-set conditions and traffic-policy statements reference as an analyzer.

Instances are immutable after creation (only tags update in place).

AddonInstance: Creating Add On Instances

import * as MailManager from "alchemy/AWS/MailManager";

const subscription = yield* MailManager.AddonSubscription("Spamhaus", {
  addonName: "SPAMHAUS_DBL",
});
const instance = yield* MailManager.AddonInstance("SpamhausInstance", {
  addonSubscriptionId: subscription.addonSubscriptionId,
});

AddonInstance: Referencing from a Traffic Policy

const policy = yield* MailManager.TrafficPolicy("Edge", {
  defaultAction: "ALLOW",
  policyStatements: [
    {
      Action: "DENY",
      Conditions: [
        {
          BooleanExpression: {
            Evaluate: {
              Analysis: {
                Analyzer: instance.addonInstanceArn,
                ResultField: "IN_DBL",
              },
            },
            Operator: "IS_TRUE",
          },
        },
      ],
    },
  ],
});

AddonSubscription

Source: src/AWS/MailManager/AddonSubscription.ts

An SES Mail Manager Add On subscription — the acceptance of a third-party Add On’s terms of use and additional pricing. An AddonInstance created from the subscription is what rule sets and traffic policies actually reference.

Subscriptions are immutable after creation (only tags update in place).

Creating a subscription accepts the Add On’s additional pricing.

AddonSubscription: Subscribing to an Add On

import * as MailManager from "alchemy/AWS/MailManager";

const subscription = yield* MailManager.AddonSubscription("Spamhaus", {
  addonName: "SPAMHAUS_DBL",
});
const instance = yield* MailManager.AddonInstance("SpamhausInstance", {
  addonSubscriptionId: subscription.addonSubscriptionId,
});

AddressList

Source: src/AWS/MailManager/AddressList.ts

An SES Mail Manager address list — a named set of email addresses that traffic policies and rule conditions can match against (allow lists, block lists, routing groups).

The list itself is create-only config (name + tags); its members are data managed at runtime via the member capabilities (RegisterMemberToAddressList, ListMembersOfAddressList, …) or bulk import jobs.

AddressList: Creating Address Lists

import * as MailManager from "alchemy/AWS/MailManager";

const blockList = yield* MailManager.AddressList("BlockList", {
  tags: { purpose: "smtp-block-list" },
});

AddressList: Managing Members at Runtime

// init — bind the member capabilities to the list
const registerMember = yield* MailManager.RegisterMemberToAddressList(blockList);
const listMembers = yield* MailManager.ListMembersOfAddressList(blockList);

// runtime
yield* registerMember({ Address: "spammer@example.com" });
const { Addresses } = yield* listMembers({});

Archive

Source: src/AWS/MailManager/Archive.ts

An SES Mail Manager email archive — durable storage for emails captured by an Archive rule action, searchable and exportable for compliance.

Deleting an archive puts it into PENDING_DELETION for 30 days before its contents are permanently removed; the archive cannot be revived, so the provider treats a pending-deletion archive as gone.

Archive: Creating Archives

import * as MailManager from "alchemy/AWS/MailManager";

const archive = yield* MailManager.Archive("Compliance", {
  retentionPeriod: "ONE_YEAR",
});

const ruleSet = yield* MailManager.RuleSet("Inbound", {
  rules: [
    {
      Name: "ArchiveAll",
      Actions: [{ Archive: { TargetArchive: archive.archiveId } }],
    },
  ],
});

Archive: Searching the Archive at Runtime

// init — bind the search capabilities to the archive
const startSearch = yield* MailManager.StartArchiveSearch(archive);
const getSearchResults = yield* MailManager.GetArchiveSearchResults(archive);

// runtime
const { SearchId } = yield* startSearch({
  FromTimestamp: new Date(Date.now() - 86_400_000),
  ToTimestamp: new Date(),
  MaxResults: 100,
});

CreateAddressListImportJob

Source: src/AWS/MailManager/CreateAddressListImportJob.ts

Runtime binding for ses:CreateAddressListImportJob.

Creates a bulk import job against the bound address list, returning the job id and a pre-signed URL to upload the address data (CSV or JSON). The address list id is injected from the binding. Provide the implementation with Effect.provide(AWS.MailManager.CreateAddressListImportJobHttp).

CreateAddressListImportJob: Bulk Importing Members

const createImportJob = yield* MailManager.CreateAddressListImportJob(blockList);

// runtime
const { JobId, PreSignedUrl } = yield* createImportJob({
  Name: "nightly-sync",
  ImportDataFormat: { ImportDataType: "CSV" },
});
// upload the CSV to PreSignedUrl, then start the job

DeregisterMemberFromAddressList

Source: src/AWS/MailManager/DeregisterMemberFromAddressList.ts

Runtime binding for ses:DeregisterMemberFromAddressList.

Removes an email address from the bound address list. The address list id is injected from the binding. Provide the implementation with Effect.provide(AWS.MailManager.DeregisterMemberFromAddressListHttp).

DeregisterMemberFromAddressList: Managing Address List Members

const deregisterMember = yield* MailManager.DeregisterMemberFromAddressList(blockList);

// runtime
yield* deregisterMember({ Address: "reformed@example.com" });

GetAddressListImportJob

Source: src/AWS/MailManager/GetAddressListImportJob.ts

Runtime binding for ses:GetAddressListImportJob.

Fetches the detail and status of an import job created against the bound address list (by JobId). IAM access is granted on the bound list’s ARN. Provide the implementation with Effect.provide(AWS.MailManager.GetAddressListImportJobHttp).

GetAddressListImportJob: Bulk Importing Members

const getImportJob = yield* MailManager.GetAddressListImportJob(blockList);

// runtime
const job = yield* getImportJob({ JobId });
if (job.Status === "COMPLETED") {
  yield* Effect.log(`imported ${job.ImportedItemsCount} addresses`);
}

GetArchiveExport

Source: src/AWS/MailManager/GetArchiveExport.ts

Runtime binding for ses:GetArchiveExport.

Fetches the parameters and status of an archive export (by ExportId). IAM access is granted on the bound archive’s ARN. Provide the implementation with Effect.provide(AWS.MailManager.GetArchiveExportHttp).

GetArchiveExport: Exporting from the Archive

const getExport = yield* MailManager.GetArchiveExport(archive);

// runtime
const status = yield* getExport({ ExportId });

GetArchiveMessage

Source: src/AWS/MailManager/GetArchiveMessage.ts

Runtime binding for ses:GetArchiveMessage.

Fetches a pre-signed download link, envelope, and ingress metadata for one archived message (by ArchivedMessageId from a search result). IAM access is granted on the bound archive’s ARN. Provide the implementation with Effect.provide(AWS.MailManager.GetArchiveMessageHttp).

GetArchiveMessage: Reading Archived Messages

const getMessage = yield* MailManager.GetArchiveMessage(archive);

// runtime
const { MessageDownloadLink, Envelope } = yield* getMessage({ ArchivedMessageId });

GetArchiveMessageContent

Source: src/AWS/MailManager/GetArchiveMessageContent.ts

Runtime binding for ses:GetArchiveMessageContent.

Fetches the parsed text/HTML body of one archived message (by ArchivedMessageId from a search result). IAM access is granted on the bound archive’s ARN. Provide the implementation with Effect.provide(AWS.MailManager.GetArchiveMessageContentHttp).

GetArchiveMessageContent: Reading Archived Messages

const getMessageContent = yield* MailManager.GetArchiveMessageContent(archive);

// runtime
const { Body } = yield* getMessageContent({ ArchivedMessageId });
yield* Effect.log(Body?.Text ?? Body?.Html ?? "(malformed)");

GetArchiveSearch

Source: src/AWS/MailManager/GetArchiveSearch.ts

Runtime binding for ses:GetArchiveSearch.

Fetches the parameters and status of an archive search (by SearchId). IAM access is granted on the bound archive’s ARN. Provide the implementation with Effect.provide(AWS.MailManager.GetArchiveSearchHttp).

GetArchiveSearch: Searching the Archive

const getSearch = yield* MailManager.GetArchiveSearch(archive);

// runtime
const search = yield* getSearch({ SearchId }).pipe(
  Effect.repeat({
    schedule: Schedule.spaced("2 seconds"),
    until: (s) => s.Status?.State === "COMPLETED" || s.Status?.State === "FAILED",
    times: 30,
  }),
);

GetArchiveSearchResults

Source: src/AWS/MailManager/GetArchiveSearchResults.ts

Runtime binding for ses:GetArchiveSearchResults.

Fetches the result rows of a completed archive search (by SearchId): sender, subject, envelope, and the ArchivedMessageId used to download each message. IAM access is granted on the bound archive’s ARN. Provide the implementation with Effect.provide(AWS.MailManager.GetArchiveSearchResultsHttp).

GetArchiveSearchResults: Searching the Archive

const getSearchResults = yield* MailManager.GetArchiveSearchResults(archive);

// runtime
const { Rows } = yield* getSearchResults({ SearchId });

GetMemberOfAddressList

Source: src/AWS/MailManager/GetMemberOfAddressList.ts

Runtime binding for ses:GetMemberOfAddressList.

Fetches a single member of the bound address list (address + registration timestamp), failing with ResourceNotFoundException when the address is not on the list. The address list id is injected from the binding. Provide the implementation with Effect.provide(AWS.MailManager.GetMemberOfAddressListHttp).

GetMemberOfAddressList: Managing Address List Members

const getMember = yield* MailManager.GetMemberOfAddressList(blockList);

// runtime
const blocked = yield* getMember({ Address: sender }).pipe(
  Effect.map(() => true),
  Effect.catchTag("ResourceNotFoundException", () => Effect.succeed(false)),
);

IngressPoint

Source: src/AWS/MailManager/IngressPoint.ts

An SES Mail Manager ingress point — the SMTP endpoint that receives incoming email, screens it with a traffic policy, and processes it with a rule set.

type and networkConfiguration are immutable (changes replace the endpoint); everything else updates in place.

IngressPoint: Creating Ingress Points

Open Ingress Point

import * as MailManager from "alchemy/AWS/MailManager";

const ruleSet = yield* MailManager.RuleSet("Inbound", {
  rules: [{ Name: "DropAll", Actions: [{ Drop: {} }] }],
});
const trafficPolicy = yield* MailManager.TrafficPolicy("Edge", {
  defaultAction: "ALLOW",
});
const ingress = yield* MailManager.IngressPoint("Smtp", {
  type: "OPEN",
  ruleSetId: ruleSet.ruleSetId,
  trafficPolicyId: trafficPolicy.trafficPolicyId,
});
// point your domain's MX record at ingress.aRecord

Authenticated Ingress Point

const ingress = yield* MailManager.IngressPoint("Smtp", {
  type: "AUTH",
  ruleSetId: ruleSet.ruleSetId,
  trafficPolicyId: trafficPolicy.trafficPolicyId,
  ingressPointConfiguration: { SecretArn: secret.secretArn },
  tlsPolicy: "REQUIRED",
});

ListAddressListImportJobs

Source: src/AWS/MailManager/ListAddressListImportJobs.ts

Runtime binding for ses:ListAddressListImportJobs.

Lists the import jobs created against the bound address list. The address list id is injected from the binding. Provide the implementation with Effect.provide(AWS.MailManager.ListAddressListImportJobsHttp).

ListAddressListImportJobs: Bulk Importing Members

const listImportJobs = yield* MailManager.ListAddressListImportJobs(blockList);

// runtime
const { ImportJobs } = yield* listImportJobs({});

ListArchiveExports

Source: src/AWS/MailManager/ListArchiveExports.ts

Runtime binding for ses:ListArchiveExports.

Lists the recent exports of the bound archive. The archive id is injected from the binding. Provide the implementation with Effect.provide(AWS.MailManager.ListArchiveExportsHttp).

ListArchiveExports: Exporting from the Archive

const listExports = yield* MailManager.ListArchiveExports(archive);

// runtime
const { Exports } = yield* listExports({});

ListArchiveSearches

Source: src/AWS/MailManager/ListArchiveSearches.ts

Runtime binding for ses:ListArchiveSearches.

Lists the recent searches of the bound archive. The archive id is injected from the binding. Provide the implementation with Effect.provide(AWS.MailManager.ListArchiveSearchesHttp).

ListArchiveSearches: Searching the Archive

const listSearches = yield* MailManager.ListArchiveSearches(archive);

// runtime
const { Searches } = yield* listSearches({});

ListMembersOfAddressList

Source: src/AWS/MailManager/ListMembersOfAddressList.ts

Runtime binding for ses:ListMembersOfAddressList.

Lists the members of the bound address list, optionally filtered by address prefix. The address list id is injected from the binding. Provide the implementation with Effect.provide(AWS.MailManager.ListMembersOfAddressListHttp).

ListMembersOfAddressList: Managing Address List Members

const listMembers = yield* MailManager.ListMembersOfAddressList(blockList);

// runtime
const { Addresses } = yield* listMembers({});

RegisterMemberToAddressList

Source: src/AWS/MailManager/RegisterMemberToAddressList.ts

Runtime binding for ses:RegisterMemberToAddressList.

Adds an email address to the bound address list. The address list id is injected from the binding. Registering an already-present address succeeds (idempotent upsert). Provide the implementation with Effect.provide(AWS.MailManager.RegisterMemberToAddressListHttp).

RegisterMemberToAddressList: Managing Address List Members

// init — bind the operation to the address list
const registerMember = yield* MailManager.RegisterMemberToAddressList(blockList);

// runtime
yield* registerMember({ Address: "spammer@example.com" });

Relay

Source: src/AWS/MailManager/Relay.ts

An SES Mail Manager relay — a downstream SMTP destination that rule-set Relay actions forward incoming email to (e.g. an on-prem Exchange server or a third-party filter).

All aspects (name, server, port, authentication, tags) update in place.

Relay: Creating Relays

Unauthenticated Relay

import * as MailManager from "alchemy/AWS/MailManager";

const relay = yield* MailManager.Relay("Downstream", {
  serverName: "smtp.example.com",
  serverPort: 25,
  authentication: { NoAuthentication: {} },
});

Authenticated Relay

const relay = yield* MailManager.Relay("Downstream", {
  serverName: "smtp.example.com",
  serverPort: 587,
  authentication: { SecretArn: secret.secretArn },
});

Relay: Using in a Rule Set

const ruleSet = yield* MailManager.RuleSet("Inbound", {
  rules: [
    {
      Name: "RelayAll",
      Actions: [{ Relay: { Relay: relay.relayId } }],
    },
  ],
});

RuleSet

Source: src/AWS/MailManager/RuleSet.ts

An SES Mail Manager rule set — the ordered rules an ingress point applies to incoming email (drop, archive, write to S3, deliver, bounce, invoke Lambda, …).

All aspects (name, rules, tags) update in place.

RuleSet: Creating Rule Sets

Drop Everything

import * as MailManager from "alchemy/AWS/MailManager";

const ruleSet = yield* MailManager.RuleSet("Inbound", {
  rules: [{ Name: "DropAll", Actions: [{ Drop: {} }] }],
});

Conditional Archive

const ruleSet = yield* MailManager.RuleSet("Inbound", {
  rules: [
    {
      Name: "ArchiveLarge",
      Conditions: [
        {
          NumberExpression: {
            Evaluate: { Attribute: "MESSAGE_SIZE" },
            Operator: "GREATER_THAN",
            Value: 1024,
          },
        },
      ],
      Actions: [{ Archive: { TargetArchive: archive.archiveId } }],
    },
  ],
});

RuleSet: Wiring to an Ingress Point

const ingress = yield* MailManager.IngressPoint("Smtp", {
  type: "OPEN",
  ruleSetId: ruleSet.ruleSetId,
  trafficPolicyId: trafficPolicy.trafficPolicyId,
});

RuleSet: Delivering Email Events to Compute

// Mail Manager has no EventBridge events or event-source mapping — email
// events reach compute through rule actions: InvokeLambda (direct),
// PublishToSns (SNS event source), or WriteToS3 (S3 event source). The
// role must be assumable by ses.amazonaws.com with lambda:InvokeFunction.
const ruleSet = yield* MailManager.RuleSet("Inbound", {
  rules: [
    {
      Name: "NotifyOnMail",
      Actions: [
        {
          InvokeLambda: {
            FunctionArn: fn.functionArn,
            InvocationType: "EVENT",
            RoleArn: invokeRole.roleArn,
          },
        },
      ],
    },
  ],
});

StartAddressListImportJob

Source: src/AWS/MailManager/StartAddressListImportJob.ts

Runtime binding for ses:StartAddressListImportJob.

Starts a created import job once its address data has been uploaded to the pre-signed URL. IAM access is granted on the bound list’s ARN. Provide the implementation with Effect.provide(AWS.MailManager.StartAddressListImportJobHttp).

StartAddressListImportJob: Bulk Importing Members

const startImportJob = yield* MailManager.StartAddressListImportJob(blockList);

// runtime
yield* startImportJob({ JobId });

StartArchiveExport

Source: src/AWS/MailManager/StartArchiveExport.ts

Runtime binding for ses:StartArchiveExport.

Starts an asynchronous export of messages from the bound archive to an S3 bucket, returning an ExportId to poll. The archive id is injected from the binding. The function also needs s3:PutObject on the destination. Provide the implementation with Effect.provide(AWS.MailManager.StartArchiveExportHttp).

StartArchiveExport: Exporting from the Archive

const startExport = yield* MailManager.StartArchiveExport(archive);

// runtime
const { ExportId } = yield* startExport({
  FromTimestamp: new Date(Date.now() - 86_400_000),
  ToTimestamp: new Date(),
  ExportDestinationConfiguration: {
    S3: { S3Location: "s3://my-export-bucket/mail/" },
  },
});

StartArchiveSearch

Source: src/AWS/MailManager/StartArchiveSearch.ts

Runtime binding for ses:StartArchiveSearch.

Starts an asynchronous search of the bound archive over a time window with optional filters, returning a SearchId to poll. The archive id is injected from the binding. Provide the implementation with Effect.provide(AWS.MailManager.StartArchiveSearchHttp).

StartArchiveSearch: Searching the Archive

const startSearch = yield* MailManager.StartArchiveSearch(archive);

// runtime
const { SearchId } = yield* startSearch({
  FromTimestamp: new Date(Date.now() - 86_400_000),
  ToTimestamp: new Date(),
  MaxResults: 100,
});

StopAddressListImportJob

Source: src/AWS/MailManager/StopAddressListImportJob.ts

Runtime binding for ses:StopAddressListImportJob.

Stops an in-flight import job. Addresses already imported remain on the list. IAM access is granted on the bound list’s ARN. Provide the implementation with Effect.provide(AWS.MailManager.StopAddressListImportJobHttp).

StopAddressListImportJob: Bulk Importing Members

const stopImportJob = yield* MailManager.StopAddressListImportJob(blockList);

// runtime
yield* stopImportJob({ JobId });

StopArchiveExport

Source: src/AWS/MailManager/StopArchiveExport.ts

Runtime binding for ses:StopArchiveExport.

Cancels a queued or running archive export (by ExportId). IAM access is granted on the bound archive’s ARN. Provide the implementation with Effect.provide(AWS.MailManager.StopArchiveExportHttp).

StopArchiveExport: Exporting from the Archive

const stopExport = yield* MailManager.StopArchiveExport(archive);

// runtime
yield* stopExport({ ExportId });

StopArchiveSearch

Source: src/AWS/MailManager/StopArchiveSearch.ts

Runtime binding for ses:StopArchiveSearch.

Cancels a queued or running archive search (by SearchId). IAM access is granted on the bound archive’s ARN. Provide the implementation with Effect.provide(AWS.MailManager.StopArchiveSearchHttp).

StopArchiveSearch: Searching the Archive

const stopSearch = yield* MailManager.StopArchiveSearch(archive);

// runtime
yield* stopSearch({ SearchId });

TrafficPolicy

Source: src/AWS/MailManager/TrafficPolicy.ts

An SES Mail Manager traffic policy — connection-level ALLOW/DENY rules an ingress point applies before email reaches the rule set (sender CIDRs, recipient patterns, TLS floor, message size cap).

All aspects (name, statements, default action, size cap, tags) update in place.

TrafficPolicy: Creating Traffic Policies

Deny-by-Default with an Allowed CIDR

import * as MailManager from "alchemy/AWS/MailManager";

const policy = yield* MailManager.TrafficPolicy("Edge", {
  defaultAction: "DENY",
  policyStatements: [
    {
      Action: "ALLOW",
      Conditions: [
        {
          IpExpression: {
            Evaluate: { Attribute: "SENDER_IP" },
            Operator: "CIDR_MATCHES",
            Values: ["10.0.0.0/8"],
          },
        },
      ],
    },
  ],
});

Allow All with a Size Cap

const policy = yield* MailManager.TrafficPolicy("Edge", {
  defaultAction: "ALLOW",
  maxMessageSizeBytes: 10 * 1024 * 1024,
});