How to Add Email to Your App with GitHub Copilot

​

Prerequisites

1. Verify a sending domain. Add the SPF, DKIM, and DMARC records from the domain setup guide.
2. Create an API key. Follow the API credentials guide and scope it to messages:send:{your-domain} instead of messages:send:all. Note your account ID.

​

Step 1: Install the SDK and Commit It

npm install @ahasend/sdk

pnpm add @ahasend/sdk

yarn add @ahasend/sdk

bun add @ahasend/sdk

​

Step 2: Write the Issue

Title: Add order-confirmation email via AhaSend Body: When an order is created, send a confirmation email using the official AhaSend TypeScript SDK, @ahasend/sdk, which is already a dependency. Do not hand-roll HTTP calls or add another email package.

• Validate AHASEND_API_KEY, AHASEND_ACCOUNT_ID, and the sender address at startup. Construct one AhaSendClient at module scope with apiKey and accountId.
• Send with client.messages.send({ from, recipients, subject, html_content, text_content }). Body fields are snake_case.
• Pass a stable, server-derived business identifier as options.idempotencyKey so an application-level retry does not create a second email. Reuse a key only for the same exact payload, and include the delivery mode in the key: keys live in one account-wide namespace shared by sandbox and live traffic, and the API matches them against a hash of the request body.
• Treat the response as multi-status: inspect every entry in result.data. A recipient can have status: "error" and a null id even though the promise resolved.
• Catch AhaSendAPIError from @ahasend/sdk and branch on structured fields, not message text. Logs may include only aggregate counts, HTTP status, SDK error code, and request ID. Never log addresses, content, bodies, headers, idempotency keys, or whole request, response, event, client, or error objects.
• Keep API keys and all AhaSend calls in server-only code. Authenticate and authorize the caller, validate input, and load the order and recipient from server-authoritative storage; do not trust a client-supplied email address or order ID. Bound the request body and rate-limit the triggering route per authenticated caller so a looping or hostile client cannot mail-bomb a customer. Escape any untrusted value before inserting it into HTML.
• Unit tests must mock the API boundary. Any explicitly approved live integration test must set sandbox: true and assert every recipient result.
• If the task involves webhooks, import WebhookVerifier from @ahasend/sdk/webhooks, verify the exact raw body, and await verifier.parse(headers, rawBody). Enforce a request-size limit, and commit the verified webhook-id and the durable work it guards in one transaction before any side effect, then run that work from a worker outside the request. A bare unique-ID insert loses the event if the process dies after the insert but before processing, and timestamp verification alone does not prevent replays.

​

Step 3: Review the Pull Request

​

Did the key stay server-side?

​

Is it using the SDK safely?

import { AhaSendAPIError, AhaSendClient } from "@ahasend/sdk";

function requiredEnv(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Missing required environment variable: ${name}`);
  return value;
}

function deliveryMode(): "sandbox" | "live" {
  const value = requiredEnv("AHASEND_DELIVERY_MODE");
  if (value !== "sandbox" && value !== "live") {
    throw new Error("AHASEND_DELIVERY_MODE must be sandbox or live");
  }
  return value;
}

const client = new AhaSendClient({
  apiKey: requiredEnv("AHASEND_API_KEY"),
  accountId: requiredEnv("AHASEND_ACCOUNT_ID"),
});

const mode = deliveryMode();
const sender = requiredEnv("AHASEND_FROM_ADDRESS");

type ConfirmedOrder = Readonly<{
  id: string;
  customerEmail: string;
}>;

export async function sendOrderConfirmation(order: ConfirmedOrder): Promise<void> {
  try {
    const result = await client.messages.send(
      {
        from: { email: sender, name: "Your Store" },
        recipients: [{ email: order.customerEmail }],
        subject: "Your order is confirmed",
        text_content: "Thanks—your order is confirmed.",
        html_content: "<p>Thanks—your order is confirmed.</p>",
        sandbox: mode === "sandbox",
      },
      { idempotencyKey: `order-confirmation-${mode}-${order.id}` },
    );

    const rejected = result.data.filter((entry) => entry.status === "error");
    if (rejected.length > 0) {
      console.warn("AhaSend rejected recipients", { count: rejected.length });
      throw new Error("Order confirmation was not accepted");
    }
  } catch (error) {
    if (error instanceof AhaSendAPIError) {
      console.error("AhaSend request failed", {
        status: error.status,
        code: error.code,
        requestId: error.requestId,
      });
      throw new Error("Email provider request failed");
    }
    throw error;
  }
}

​

Does it handle retries and multi-status results?

​

Step 4: Test Without Giving the Agent a Production Credential

​

Step 5: Merge and Send a Real Email

• Set AHASEND_API_KEY, AHASEND_ACCOUNT_ID, and AHASEND_FROM_ADDRESS in the hosting platform’s secret store.
• Set AHASEND_DELIVERY_MODE explicitly to live; fail closed when it is absent or invalid.
• Send one confirmation to an address you control and verify the result and delivery.

​

Going Further

• Exercise sandbox outcomes: integration tests can set sandbox_result to bounce or suppress to exercise the corresponding delivery and webhook paths. Assert multi-status send results separately.
• Templating and webhooks: per-recipient substitutions support personalized batches, and @ahasend/sdk/webhooks verifies delivery-event signatures. Preserve the raw body, and commit webhook-id together with the durable work in one transaction before any side effect.
• Same grounding technique, different instruction file: Cursor, Claude, and Windsurf.
• For complete framework integrations, see Next.js, Express, or Remix.

​

Troubleshooting