Elastic Email Examples

Real-world examples for building with the Elastic Email API, SMTP, webhooks and AI coding agents.

Quick Start · SMTP · AI Agents · API Docs · Get an API Key

Production-shaped code samples for the Elastic Email email API
and SMTP relay, in 21 languages, frameworks and serverless platforms. Every stack implements the same
use cases through the official SDKs and REST API v4, so what you learn in one maps directly to the
others.

import {
  Configuration,
  EmailsApi,
} from "@elasticemail/elasticemail-client-ts-axios";

const emailsApi = new EmailsApi(
  new Configuration({
    apiKey: process.env.ELASTICEMAIL_API_KEY,
  })
);

await emailsApi.emailsTransactionalPost({
  Recipients: { To: ["[email protected]"] },
  Content: {
    From: process.env.EMAIL_FROM!, // must be on a domain verified in Elastic Email
    Subject: "Hello from Elastic Email",
    Body: [
      { ContentType: "HTML", Content: "<p>Hello!</p>" },
      { ContentType: "PlainText", Content: "Hello!" },
    ],
  },
});

Start building

Pick your stack and send your first email in about five minutes.

Something else? Ruby, Rust, Elixir, plain Node.js, Hono, Bun, the full-stack JavaScript frameworks,
serverless platforms and SMTP are all in All stacks.

What is included

• Transactional and bulk email
• Templates and merge variables
• Attachments and inline images
• Contacts and lists
• Webhooks
• Inbound email
• SMTP examples
• Serverless examples
• Claude Code and AI agent support
• MCP integration

Every example runs on the free plan - see plans and pricing.

Using with AI agents

The repository includes support for Claude Code, agent skills, MCP and LLM-readable documentation.

npx skills add ElasticEmail/elasticemail-examples

These examples are laid out so a coding agent can find the right file and copy working code
into your project instead of guessing at the API.

Install the skill in Claude Code:

/plugin marketplace add ElasticEmail/elasticemail-examples
/plugin install elasticemail@elasticemail

For other agents that support skills, copy skills/elasticemail/ into the agent's skills folder
(for example .cursor/skills/ or ~/.codex/skills/), or use the npx skills add command above.

Give the agent API access with the Elastic Email MCP server.
It sends email and manages contacts, lists, segments, templates and campaigns. The server runs on your
machine (.NET 10, listening on port 5001) and takes your API key in the X-Auth-Token header:

# Claude Code
claude mcp add --transport http elasticemail http://localhost:5001/ --header "X-Auth-Token: $ELASTICEMAIL_API_KEY"

// Cursor: ~/.cursor/mcp.json
{ "mcpServers": { "elasticemail": { "url": "http://localhost:5001/", "headers": { "X-Auth-Token": "<api key>" } } } }

// VS Code: .vscode/mcp.json
{ "servers": { "elasticemail": { "type": "http", "url": "http://localhost:5001/", "headers": { "X-Auth-Token": "<api key>" } } } }

All stacks

Each quickstart is five minutes from nothing to a delivered email; the folder it links to covers
every example and route for that language.

JavaScript and TypeScript stacks use @elasticemail/elasticemail-client-ts-axios. Other languages use the matching Elastic Email SDK. Elixir calls the REST API directly with Req.
All stacks are pinned to the 4.2 SDK line and target REST API v4.

Send with SMTP

Some tools only let you enter an SMTP server: Auth0, Supabase Auth, WordPress, Metabase. Some apps
already send through their framework's mailer. For both, smtp-elasticemail-examples/
shows how to point them at smtp.elasticemail.com, with no SDK involved. The
SMTP quickstart sends a first message with curl.

SMTP uses its own credentials (Settings > SMTP in the dashboard), not the API key.

Examples Included

Every language and framework stack covers the sending, webhook, inbound, contacts, double opt-in and
domain examples. The full-stack framework apps (Next.js, Remix, Nuxt, SvelteKit, Astro, RedwoodJS,
TanStack Start, Laravel) skip some account-level ones, and the serverless folders focus on send and webhooks.
examples.json lists exactly which files cover which use case in each stack.

Sending

• Basic Send - HTML and plain text transactional email
• Batch Send - One bulk call with per-recipient merge fields
• With Attachments - Base64 file attachments
• With CID Attachments - Inline images referenced by Content-ID
• With Templates - Hosted templates with merge variables (created on first run)
• Scheduled Send - Delayed delivery with TimeOffset
• Prevent Threading - Unique X-Entity-Ref-ID header per message
• Email Status - Look up a transaction and view a sent message

Receiving

• Webhooks - Create webhooks and handle Sent, Opened, Clicked, Error, AbuseReport and Unsubscribed events
• Inbound - Inbound routes that push parsed email to your endpoint

Contacts and lists

• Contacts - Lists, contact CRUD, custom fields
• Double Opt-in - Confirmation link with an HMAC token, or confirmation through the Clicked event
• Suppressions - Unsubscribe, bounce and complaint lists

Account

• Domains - Add a sending domain and read SPF, DKIM, MX, DMARC and tracking status
• Statistics - Account-level delivery statistics
• Email Verification - Single address verification
• Sub-accounts - List sub-accounts, and optionally create one and assign credits

Guides

Language-neutral explanations of the concepts every example uses. Start with the quickstart for your
stack, come here when you need the detail.

Getting Started

1. Get an API key from app.elasticemail.com.
   Copy it straight away - it is shown once. API settings covers creating and managing keys.

2. Verify a sender domain in the Elastic Email dashboard. Examples send from EMAIL_FROM, which must belong to a verified domain.
   Publishing the SPF and DKIM records takes a few minutes - How to verify your domain walks through it.

3. Clone this repository:

   git clone https://github.com/ElasticEmail/elasticemail-examples.git
   

4. Choose your stack and follow its README

5. Copy .env.example to .env and fill in ELASTICEMAIL_API_KEY, EMAIL_FROM and EMAIL_TO

6. Run the examples

Notes on webhooks and inbound

Elastic Email does not sign webhook requests. Every example appends a shared secret to the callback URL
(?token=ELASTICEMAIL_WEBHOOK_TOKEN) and verifies it with a constant-time compare. Elastic Email sends each event
as a GET request with the details in the query string (status, to, transaction, messageid, category,
target). Inbound email is different: it arrives as a POST with form fields (from_email, subject,
body_text, body_html, att1_name, att1_content, ...).

When you save a webhook, Elastic Email sends one test event to the URL and saves the webhook only if it gets a
2xx response, so the URL has to be publicly reachable at that moment. During local development, run a tunnel
such as ngrok and set PUBLIC_URL accordingly. The test event carries sample values ([email protected],
messageid=abc1234). The handlers accept it like any other event; in your own app, skip it before it reaches
your data.

Full detail: Webhooks and Inbound email.

Resources

• Elastic Email email API - REST API and SMTP relay overview, features and plans
• Elastic Email Developers
• REST API Reference
• API Libraries
• Elastic Email CLI
• Elastic Email MCP server
• Dashboard

Contributing

Found a problem or want to add a stack? Open an issue or send a pull request.
CONTRIBUTING.md covers the conventions and how to add a stack. To report a security
issue, see SECURITY.md.

License

MIT