Send email with Nuxt

Quickstart#

1. Install the SDK

   bash

   npm install @poststack.dev/sdk

2. Add the key to runtime config

   typescript

   // nuxt.config.ts
   export default defineNuxtConfig({
     runtimeConfig: {
       // server-only; set it with the NUXT_POSTSTACK_API_KEY environment variable
       poststackApiKey: '',
     },
   });
   
   // server/utils/poststack.ts — auto-imported in every server route
   import type { H3Event } from 'h3';
   import { PostStack } from '@poststack.dev/sdk';
   
   let client: PostStack | undefined;
   
   // Pass the event in routes so edge presets (Cloudflare) read the key from the
   // request's env. Nitro tasks have no event; there it falls back to process config.
   export function usePostStack(event?: H3Event) {
     client ??= new PostStack(useRuntimeConfig(event).poststackApiKey);
     return client;
   }

3. Send from a server route

   typescript

   // server/api/send.post.ts  ->  POST /api/send
   import { PostStackError } from '@poststack.dev/sdk';
   
   export default defineEventHandler(async (event) => {
     const { email, name } = await readBody<{ email: string; name: string }>(event);
   
     try {
       const { id } = await usePostStack(event).emails.send({
         from: 'Acme <hello@yourdomain.com>',   // must be on a verified domain
         to: [email],                           // always an array
         subject: `Welcome, ${name}`,
         html: `<h1>Welcome, ${name}!</h1>`,
         text: `Welcome, ${name}!`,
       });
       return { id };                           // "em_..."
     } catch (err) {
       if (err instanceof PostStackError) {
         throw createError({ statusCode: err.statusCode, statusMessage: err.message });
       }
       throw err;
     }
   });

4. Handle errors

   typescript

   // server/api/contact.post.ts — validate input, then map PostStack errors
   import { z } from 'zod';
   import { PostStackError } from '@poststack.dev/sdk';
   
   const Contact = z.object({
     email: z.string().email(),
     message: z.string().min(1).max(5000),
   });
   
   export default defineEventHandler(async (event) => {
     const body = await readValidatedBody(event, Contact.parse); // 400 on bad input
   
     try {
       // The SDK already retries 408, 429 and 5xx with backoff and an idempotency key.
       const { id } = await usePostStack(event).emails.send({
         from: 'Website <contact@yourdomain.com>',
         to: ['support@yourdomain.com'],
         reply_to: body.email,
         subject: 'New contact form message',
         text: body.message,
       });
       return { id };
     } catch (err) {
       if (!(err instanceof PostStackError)) throw err; // network error after retries
       console.error('PostStack error', {
         status: err.statusCode,
         message: err.message,
         requestId: err.requestId,
       });
       // 422 = unverified from-domain or suppressed recipient; 401/403 = key problem
       throw createError({
         statusCode: err.statusCode >= 500 ? 502 : err.statusCode,
         statusMessage: 'Could not send your message',
       });
     }
   });

Call the route from a page#

Use $fetch in an event handler (not useFetch, which runs on render). The API key stays on the server.

<!-- pages/signup.vue -->
<script setup lang="ts">
const email = ref('');
const status = ref<'idle' | 'sent' | 'error'>('idle');

async function submit() {
  try {
    await $fetch('/api/send', { method: 'POST', body: { email: email.value, name: 'there' } });
    status.value = 'sent';
  } catch {
    status.value = 'error';
  }
}
</script>

<template>
  <form @submit.prevent="submit">
    <input v-model="email" type="email" required />
    <button type="submit">Send welcome email</button>
    <p v-if="status === 'sent'">Check your inbox.</p>
    <p v-if="status === 'error'">Something went wrong.</p>
  </form>
</template>

Attachments#

Attachments are base64 strings. Read uploads with readMultipartFormData. Limits: 10 attachments, 10 MB per file, 25 MB in total.

// server/api/report.post.ts
export default defineEventHandler(async (event) => {
  const parts = (await readMultipartFormData(event)) ?? [];
  const file = parts.find((p) => p.name === 'file' && p.filename);
  if (!file) throw createError({ statusCode: 400, statusMessage: 'No file' });

  const { id } = await usePostStack(event).emails.send({
    from: 'reports@yourdomain.com',
    to: ['team@yourdomain.com'],
    subject: `Report: ${file.filename}`,
    text: 'Report attached.',
    attachments: [
      {
        filename: file.filename!,
        content: Buffer.from(file.data).toString('base64'),
        content_type: file.type,
      },
    ],
  });
  return { id };
});

Framework integrations#

Common pitfalls#

FAQ#

Next steps