Mailcraft Adapter Integration Guide

This document explains how to configure and use Mailcraft adapters with real email providers.

Resend Adapter

The Resend adapter uses the official Resend SDK to send emails.

Setup

import { Mailcraft } from "@mailcraft/sdk";
import { ResendAdapter } from "@mailcraft/adapters/resend";

// Option 1: Provide API key directly
const adapter = new ResendAdapter("re_your_resend_api_key");

// Option 2: Use environment variable (RESEND_API_KEY)
const adapter = new ResendAdapter();

// Option 3: Mock mode for testing (no credentials needed)
const adapter = new ResendAdapter(); // Returns mock responses if no API key configured

Usage

const mailcraft = new Mailcraft({
  name: "My App",
  sender: {
    fromEmail: "noreply@myapp.com",
    fromName: "My App"
  },
  business: {
    legalName: "My App Inc."
  }
});

// Send verification email via Resend
const result = await mailcraft.send(
  "verification",
  {
    to: ["user@example.com"],
    code: "123456",
    link: "https://myapp.com/verify?token=abc123"
  },
  adapter
);

console.log(`Email sent with ID: ${result.id}`);
console.log(`Message ID: ${result.metadata?.messageId}`);

Environment Variables

  • RESEND_API_KEY: Your Resend API key

AWS SES Adapter

The SES adapter uses the official AWS SDK for JavaScript to send emails through Amazon SES.

Setup

import { Mailcraft } from "@mailcraft/sdk";
import { SesAdapter } from "@mailcraft/adapters/ses";

// Option 1: Specify region directly
const adapter = new SesAdapter("us-east-1");

// Option 2: Use environment variable (AWS_REGION)
const adapter = new SesAdapter();

// Option 3: Mock mode for testing (no credentials needed)
const adapter = new SesAdapter(); // Returns mock responses if no region configured

Usage

const mailcraft = new Mailcraft({
  name: "My App",
  sender: {
    fromEmail: "noreply@myapp.com",
    fromName: "My App"
  },
  business: {
    legalName: "My App Inc."
  }
});

// Send receipt email via SES
const result = await mailcraft.send(
  "receipt",
  {
    to: ["customer@example.com"],
    receiptId: "RCP-2024-001",
    currency: "USD",
    total: "99.99",
    items: [
      { name: "Premium Plan", quantity: 1, amount: "$99.99" }
    ]
  },
  adapter
);

console.log(`Email sent with ID: ${result.id}`);
console.log(`Sequence Token: ${result.metadata?.sequenceToken}`);

Environment Variables

  • AWS_REGION: AWS region (e.g., us-east-1)
  • AWS credentials are configured via standard AWS SDK mechanisms:
    • Environment variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
    • AWS credentials file: ~/.aws/credentials
    • IAM roles (if running on EC2, Lambda, etc.)

IAM Permissions Required

For SES adapter to work, your AWS user/role needs these permissions:

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

Error Handling

Both adapters validate input before attempting to send and throw MailcraftSendError if the send fails:

try {
  const result = await mailcraft.send("verification", input, adapter);
} catch (error) {
  if (error instanceof MailcraftSendError) {
    console.error(`Send failed via ${error.provider}: ${error.payload.reason}`);
    console.error(`Archetype: ${error.payload.archetype}`);
    console.error(`Original cause:`, error.cause);
  }
}

Testing & Mock Mode

Both adapters automatically fall back to mock mode if:

  • Resend: No RESEND_API_KEY environment variable and no API key passed to constructor
  • SES: No AWS_REGION environment variable and no region passed to constructor

In mock mode, sends return realistic response structures but don't actually send emails. This is useful for:

  • Unit testing
  • Local development
  • CI/CD pipelines

Response Structure

Success responses include provider-specific metadata:

Resend

{
  "id": "01j...",
  "provider": "resend",
  "acceptedAt": "2024-04-25T06:00:00.000Z",
  "metadata": {
    "messageId": "01j..."
  }
}

SES

{
  "id": "0000...",
  "provider": "ses",
  "acceptedAt": "2024-04-25T06:00:00.000Z",
  "metadata": {
    "sequenceToken": "0000..."
  }
}

Next Steps