How to Integrate Bolt.new with Mailgun

Go to mailgun.com and sign up for a free account. Mailgun's free plan provides 1,000 emails per month with no credit card required, which is sufficient for development and small-scale use. After confirming your email, you will land in the Mailgun dashboard. The first thing you need is a sending domain. Mailgun automatically provisions a sandbox domain for you — it looks like sandbox12345abc.mailgun.org. This sandbox domain works immediately and requires no DNS configuration, making it perfect for development. However, it can only send to email addresses you explicitly authorize in the Mailgun dashboard under 'Authorized Recipients.' This restriction exists to prevent abuse on free accounts. For a production app, you will want to verify your own domain (e.g., mail.yourdomain.com). In the Mailgun dashboard, click 'Domains' in the left sidebar, then 'Add New Domain.' Enter your domain, select your region (US or EU), and click 'Add Domain.' Mailgun will provide DNS records — a TXT record for SPF, a TXT record for DKIM, and optionally a CNAME for tracking. Add these records in your domain registrar's DNS settings. Verification typically takes 5-30 minutes. Next, get your API key. In the Mailgun dashboard, go to Settings → API Keys. Copy the Private API Key — it starts with 'key-' and is a long alphanumeric string. This is the key you will add to your .env file. Keep this key confidential; it has full access to your Mailgun account. Also note your sending domain — you will need both the API key and the domain in your environment variables. Finally, note your Mailgun API base URL. If you are on Mailgun's US region (default), use https://api.mailgun.net. If you selected the EU region, use https://api.eu.mailgun.net. The base URL varies by region and must match where your account is hosted.

With your Mailgun credentials in hand, prompt Bolt to scaffold the entire email integration. The mailgun.js SDK is a pure JavaScript library maintained by Mailgun that wraps the REST API. It is compatible with Bolt's WebContainer because it uses the native fetch API internally — no native Node.js modules or C extensions are needed. The API route you will create lives at app/api/email/route.ts in a Next.js project. This server-side route accepts a POST request from your React components, validates the input, and calls Mailgun's API. By keeping all Mailgun calls in this route, your private API key never reaches the browser bundle. Paste the following prompt into Bolt's chat to generate the complete setup. After Bolt generates the code, review app/api/email/route.ts to confirm it reads from process.env.MAILGUN_API_KEY and process.env.MAILGUN_DOMAIN. Check that no Mailgun credentials appear in any client-side component files. Also verify that Bolt added 'mailgun.js' and 'form-data' to package.json — the form-data package is required as a peer dependency for mailgun.js. Note: Bolt's WebContainer will install mailgun.js from the npm CDN-backed cache, typically completing within a few seconds. If you see an installation error, it may be because a transient WebContainer network issue occurred — try prompting Bolt to 'Reinstall dependencies' or restart the dev server.

1// lib/mailgun.ts
2import Mailgun from 'mailgun.js';
3import FormData from 'form-data';
4
5const mailgun = new Mailgun(FormData);
6
7const mg = mailgun.client({
8  username: 'api',
9  key: process.env.MAILGUN_API_KEY ?? '',
10  // Use 'https://api.eu.mailgun.net' for EU region accounts
11  url: 'https://api.mailgun.net',
12});
13
14const DOMAIN = process.env.MAILGUN_DOMAIN ?? '';
15const FROM = process.env.MAILGUN_FROM_EMAIL ?? `noreply@${DOMAIN}`;
16
17export interface EmailOptions {
18  to: string | string[];
19  subject: string;
20  html: string;
21  text: string;
22  replyTo?: string;
23  template?: string;
24  templateVariables?: Record<string, string>;
25}
26
27export async function sendEmail(options: EmailOptions) {
28  if (!process.env.MAILGUN_API_KEY || !DOMAIN) {
29    throw new Error('Mailgun credentials not configured');
30  }
31
32  const messageData: Record<string, unknown> = {
33    from: FROM,
34    to: options.to,
35    subject: options.subject,
36    html: options.html,
37    text: options.text,
38  };
39
40  if (options.replyTo) {
41    messageData['h:Reply-To'] = options.replyTo;
42  }
43
44  if (options.template) {
45    messageData.template = options.template;
46    messageData['h:X-Mailgun-Variables'] = JSON.stringify(options.templateVariables ?? {});
47  }
48
49  return mg.messages.create(DOMAIN, messageData as Parameters<typeof mg.messages.create>[1]);
50}

Open the .env file in Bolt's file explorer and replace the placeholder values with your actual Mailgun credentials. You need three values: MAILGUN_API_KEY (your private API key starting with 'key-'), MAILGUN_DOMAIN (your sandbox or custom domain like sandbox12345.mailgun.org or mail.yourdomain.com), and optionally MAILGUN_FROM_EMAIL (the 'from' address for outgoing emails — must match or be a subdomain of your sending domain). With the credentials in place, prompt Bolt to build a contact form component that calls the /api/email route. The contact form should be a standard React component with controlled inputs for name, email, and message, a submit handler that calls fetch('/api/email', { method: 'POST', ... }), and state management for loading and success/error states. After Bolt generates the form, click the Bolt preview to test it. Fill in the form fields and click submit. In Bolt's terminal panel at the bottom, you should see the Next.js dev server log the API route being called. After a few seconds, check your inbox (if you added your email as an Authorized Recipient in Mailgun). You should receive the test email. If no email arrives within 2 minutes, go to your Mailgun dashboard → Logs → see if the message was accepted or rejected. The Mailgun Logs panel is excellent for debugging — it shows the exact delivery status and any error messages. Outbound email from the Next.js API route works in Bolt's WebContainer without any deployment step. This is because outbound HTTPS calls to Mailgun's API servers are just regular fetch() calls — they work from any Node.js runtime, including WebContainers. This is a significant advantage over services that require webhooks for even basic sending.

1# .env
2# Mailgun credentials — server-side only, never use NEXT_PUBLIC_ prefix
3MAILGUN_API_KEY=key-your_private_api_key_here
4MAILGUN_DOMAIN=sandboxABCDEF123456.mailgun.org
5MAILGUN_FROM_EMAIL=noreply@sandboxABCDEF123456.mailgun.org
6
7# For EU region accounts, update the url in lib/mailgun.ts:
8# url: 'https://api.eu.mailgun.net'

Hardcoding HTML in your API route is fine for simple one-off emails, but for an app sending multiple types of transactional email — welcome messages, password resets, order confirmations — Mailgun's template system is a much better approach. Templates are managed in the Mailgun dashboard, support Handlebars syntax for variable substitution, can be version-controlled, and let non-developers update email copy without touching code. To create a template, go to your Mailgun dashboard → Email Templates → Create Message. Give it a name like 'welcome-email.' Use Mailgun's visual template builder or paste in raw HTML. Add Handlebars variable placeholders like {{name}}, {{confirm_link}}, and {{company_name}} where you want dynamic content. Save the template. In your Bolt app, update the sendEmail function in lib/mailgun.ts to support template-based sending. When a template name is provided, Mailgun's API uses the stored template instead of the html/text fields, substituting the variables you pass as 'h:X-Mailgun-Variables.' The template system also handles plain-text fallback automatically when configured in the template settings. Template versioning is a powerful feature: create multiple versions of a template (version 1, version 2, etc.) and deploy them independently. The API always uses the 'active' version, so you can test new designs by activating a draft without changing code. This separation of email design from application logic is a significant advantage for teams where designers and developers work independently.

1// lib/email-templates.ts
2import { sendEmail } from './mailgun';
3
4// Welcome email using Mailgun template
5export async function sendWelcomeEmail(to: string, name: string, confirmLink: string) {
6  return sendEmail({
7    to,
8    subject: `Welcome to our app, ${name}!`,
9    // html and text are ignored when using a template
10    html: '',
11    text: `Welcome ${name}! Confirm your email: ${confirmLink}`,
12    template: 'welcome-email',
13    templateVariables: {
14      name,
15      confirm_link: confirmLink,
16      company_name: 'My App',
17    },
18  });
19}
20
21// Password reset email
22export async function sendPasswordResetEmail(to: string, resetLink: string) {
23  return sendEmail({
24    to,
25    subject: 'Reset your password',
26    html: '',
27    text: `Click this link to reset your password: ${resetLink}`,
28    template: 'password-reset',
29    templateVariables: {
30      reset_link: resetLink,
31      expiry_hours: '2',
32    },
33  });
34}

Mailgun can notify your app in real time when email events occur: a recipient opened your email, clicked a link, unsubscribed, or — most importantly — when an email bounced or a recipient marked it as spam. These event notifications are delivered via webhooks — HTTP POST requests that Mailgun sends to a URL you specify. Because webhooks require a publicly accessible URL, they cannot be tested in Bolt's WebContainer, which has no public endpoint. This is the one part of the Mailgun integration that requires a deployment step first. Deploy your app to Netlify (using Bolt's native Netlify integration under Settings → Applications) or Bolt Cloud (click the Publish button). Once deployed, you will have a public URL like yourapp.netlify.app or yourapp.bolt.host. In the Bolt terminal, run the build to verify there are no errors: this is a good check before deploying. After deployment, go to your Netlify or Bolt Cloud dashboard and add the environment variables: MAILGUN_API_KEY, MAILGUN_DOMAIN, and MAILGUN_FROM_EMAIL. Without these, the deployed app's email API route will return 500 errors. Trigger a redeploy after adding variables. Then create a webhook handler. In Bolt, add an API route at app/api/webhooks/mailgun/route.ts. This route accepts POST requests from Mailgun containing event data. Mailgun sends a signed webhook with a timestamp, token, and HMAC-SHA256 signature using your webhook signing key (found in Mailgun Settings → Webhooks → Webhook signing key). You should verify this signature before processing events to prevent abuse. Finally, register the webhook URL in the Mailgun dashboard: Settings → Webhooks → Add webhook. Enter your deployed URL (https://yourapp.netlify.app/api/webhooks/mailgun) and select the events you want to track. Click Test Webhook to verify Mailgun can reach your endpoint.

1// app/api/webhooks/mailgun/route.ts
2import { NextResponse } from 'next/server';
3import crypto from 'crypto';
4
5function verifyMailgunSignature(
6  signingKey: string,
7  timestamp: string,
8  token: string,
9  signature: string
10): boolean {
11  const value = timestamp + token;
12  const hmac = crypto.createHmac('sha256', signingKey).update(value).digest('hex');
13  return hmac === signature;
14}
15
16export async function POST(request: Request) {
17  const signingKey = process.env.MAILGUN_WEBHOOK_KEY;
18  if (!signingKey) {
19    return NextResponse.json({ error: 'Webhook key not configured' }, { status: 500 });
20  }
21
22  const body = await request.json();
23  const { signature, 'event-data': eventData } = body;
24
25  // Verify webhook authenticity
26  const isValid = verifyMailgunSignature(
27    signingKey,
28    signature.timestamp,
29    signature.token,
30    signature.signature
31  );
32
33  if (!isValid) {
34    return NextResponse.json({ error: 'Invalid signature' }, { status: 401 });
35  }
36
37  const eventType = eventData?.event;
38  const recipient = eventData?.recipient;
39
40  console.log(`Mailgun event: ${eventType} for ${recipient}`);
41
42  // Handle specific events
43  switch (eventType) {
44    case 'bounced':
45      // Mark email as undeliverable in your database
46      break;
47    case 'complained':
48      // Unsubscribe user from future emails
49      break;
50    case 'unsubscribed':
51      // Update user preferences in database
52      break;
53  }
54
55  return NextResponse.json({ received: true });
56}