---
title: "Email"
description: "Send email from an app with Vue templates, without a mail provider of your own."
canonical_url: "https://docs.lightdrop.cloud/guides/email"
---
# Email

> Send email from an app with Vue templates, without a mail provider of your own.

Apps send email through wervt: write a template as a Vue component, call `sendMail()`, and the
platform delivers it. No provider account, API key or DNS setup per app.

## Templates

Templates live in `emails/` and use the components from `@wervt/nuxt/email`. Out of the box they
look like wervt.app: a ruled frame with crosshair corners, a dark header with the wervt logo and
the app's name, a white body with blue buttons, and a footer that says which app sent the mail and
why. [Your own look](#your-own-look) swaps that for the app's name, logo, colors and layout.

```vue
<!-- emails/Welcome.vue -->
<script lang="ts">
// Sample data for the preview at /_wervt/emails.
export const previewProps = { name: 'Ada', url: 'https://todos.lightdrop.cloud' }
</script>

<script setup lang="ts">
import { EmailButton, EmailHeading, EmailText, WervtEmail } from '@wervt/nuxt/email'

defineProps<{ name: string; url: string }>()
</script>

<template>
  <WervtEmail
    subject="Welcome to todos"
    app="todos"
    :preview="`Hi ${name}, your list is ready`"
    reason="You get this because you signed up for todos."
  >
    <EmailHeading eyebrow="Welcome">Your list is ready</EmailHeading>
    <EmailText>Hi {{ name }}, your list is ready.</EmailText>
    <EmailButton :href="url">Open todos</EmailButton>
  </WervtEmail>
</template>
```

<table>
<thead>
  <tr>
    <th>
      Component
    </th>
    
    <th>
      
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        WervtEmail
      </code>
    </td>
    
    <td>
      The whole email, at the root of a template. Props: <code>
        subject
      </code>
      
      , <code>
        app
      </code>
      
       (shown in the header and footer), <code>
        preview
      </code>
      
       (the line inboxes show after the subject), <code>
        reason
      </code>
      
       (why the recipient got the mail, in the footer), <code>
        footer
      </code>
      
       (replaces "Sent by <app>
        via wervt"), <code>
          lang
        </code>
        
         (<code>
          en
        </code>
        
         or <code>
          de
        </code>
        
        , for the footer's own texts and <code>
          <html lang>
        </code>
        
        ), and <code>
          brand
        </code>
        
        , <code>
          theme
        </code>
        
         and <code>
          frame
        </code>
        
         for <a href="#your-own-look">
          your own look
        </a>
        
        . Slots: <code>
          header
        </code>
        
         and <code>
          footer
        </code>
      </app>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        EmailDocument
      </code>
    </td>
    
    <td>
      A bare root instead of <code>
        WervtEmail
      </code>
      
      , for <a href="#a-layout-of-your-own">
        a layout of your own
      </a>
      
      . Props: <code>
        subject
      </code>
      
      , <code>
        preview
      </code>
      
      , <code>
        lang
      </code>
      
      , <code>
        theme
      </code>
      
      , <code>
        width
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        EmailHeading
      </code>
    </td>
    
    <td>
      A heading, with an optional <code>
        eyebrow
      </code>
      
       label above it
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        EmailText
      </code>
    </td>
    
    <td>
      A paragraph
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        EmailMuted
      </code>
    </td>
    
    <td>
      Smaller, gray text for hints
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        EmailLink
      </code>
    </td>
    
    <td>
      A link (<code>
        href
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        EmailButton
      </code>
    </td>
    
    <td>
      A button (<code>
        href
      </code>
      
      ) that also renders in Outlook; <code>
        color="neutral"
      </code>
      
       for black instead of the theme's color, or a hex color of its own
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        EmailCode
      </code>
    </td>
    
    <td>
      A one-time code, large and spaced (<code>
        code
      </code>
      
      ), with an optional <code>
        caption
      </code>
      
       under it
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        EmailDivider
      </code>
    </td>
    
    <td>
      A horizontal line
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        InviteEmail
      </code>
    </td>
    
    <td>
      A whole invitation, ready to send: <code>
        by
      </code>
      
      , <code>
        app
      </code>
      
      , <code>
        url
      </code>
      
      , and optionally <code>
        message
      </code>
      
       (a sentence about the app), <code>
        action
      </code>
      
       (the button label), <code>
        note
      </code>
      
       (the hint under it) and <code>
        lang
      </code>
      
       (<code>
        en
      </code>
      
       or <code>
        de
      </code>
      
      ; <code>
        message
      </code>
      
      , <code>
        action
      </code>
      
       and <code>
        note
      </code>
      
       stay as you wrote them)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        LogAlertEmail
      </code>
    </td>
    
    <td>
      The mail wervt sends when a <a href="https://docs.lightdrop.cloud/guides/logs#saved-queries-and-alerts">
        log alert
      </a>
      
       fires: <code>
        app
      </code>
      
      , <code>
        name
      </code>
      
      , <code>
        query
      </code>
      
      , <code>
        count
      </code>
      
      , <code>
        threshold
      </code>
      
      , <code>
        window
      </code>
      
      , <code>
        cooldown
      </code>
      
      , <code>
        url
      </code>
      
       and the newest matches as <code>
        samples
      </code>
    </td>
  </tr>
</tbody>
</table>

Mail clients ignore most CSS, so the components use tables and inline styles. Stick to them and
plain inline elements (`strong`, `em`, `br`); flexbox, grid and classes won't survive. The logo
is a PNG served from wervt.app, because Gmail and Outlook don't show SVG; with images blocked its
alt text takes its place. Clients that support it get a dark version of the mail.

## Your own look

Set `wervt.email` and every mail of the app, the ready-made `InviteEmail` included, carries the
app's name, logo and colors instead of wervt's:

```ts [nuxt.config.ts]
wervt: {
  email: {
    brand: {
      name: 'Todos', // in the header and "Sent by Todos"
      icon: '/mail/icon.png', // square, next to the name
      logo: '/mail/logo.png', // wide, instead of icon and name, shown 32px high
      securedByWervt: false, // drops "Secured by wervt" from the footer
    },
    theme: {
      accent: '#16a34a', // buttons, links, eyebrows, the code box and the line under the header
      band: '#ffffff', // the header band
      radius: '12px',
      font: "Inter, -apple-system, 'Segoe UI', sans-serif",
    },
    frame: 'card', // 'ruled' (wervt's hairlines), 'card' or 'none'
  },
}
```

An app with [`wervt.brand`](https://docs.lightdrop.cloud/api/module#login-branding) needs none of this to start with: its
mails take over the login's name, icon and color, so the sign-in code and the mails after it look
like one sender. `email.brand` then only changes what should differ, and `email: { brand: false }`
keeps wervt's header. Without `wervt.brand`, `email: { brand: true }` takes name and icon from
`app.head`.

Images are PNG, JPEG or GIF (Gmail and Outlook don't show SVG), as a path in `public/` or an
https URL. Mail clients load them without a login, so on a private app a file in `public/` shows
the login page instead: use the icon of `wervt.brand`, which wervt serves to everyone, or host
the image elsewhere.

### Theme

`accent` is usually enough: the button, the tint of the code box and the dark version's accent
follow from it, and the button's label turns dark on a light color. Everything else can be set
on its own:

<table>
<thead>
  <tr>
    <th>
      Token
    </th>
    
    <th>
      
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        accent
      </code>
    </td>
    
    <td>
      Links, eyebrows, the line under the header; buttons unless <code>
        button
      </code>
      
       is set
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        button
      </code>
      
      , <code>
        buttonText
      </code>
    </td>
    
    <td>
      The button's background and label
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        band
      </code>
    </td>
    
    <td>
      The header band behind logo and name; the name turns dark on a light band
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        page
      </code>
      
      , <code>
        card
      </code>
    </td>
    
    <td>
      Behind the mail and the footer; behind the body
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        text
      </code>
      
      , <code>
        highlighted
      </code>
      
      , <code>
        muted
      </code>
      
      , <code>
        dimmed
      </code>
    </td>
    
    <td>
      Body text; headings and codes; hints; the footer's last line
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        border
      </code>
    </td>
    
    <td>
      The frame and dividers
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        codeBackground
      </code>
      
      , <code>
        accentBorder
      </code>
    </td>
    
    <td>
      The code box and its border
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        radius
      </code>
    </td>
    
    <td>
      Corners of buttons and of the <code>
        card
      </code>
      
       frame
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        font
      </code>
      
      , <code>
        mono
      </code>
    </td>
    
    <td>
      Font stacks. Only Apple Mail loads web fonts, so end them with system fonts
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        fontUrl
      </code>
    </td>
    
    <td>
      A stylesheet with the web fonts the stacks name; with a <code>
        font
      </code>
      
       of your own and no <code>
        fontUrl
      </code>
      
      , none is loaded
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        dark
      </code>
    </td>
    
    <td>
      The colors of the dark version (<code>
        page
      </code>
      
      , <code>
        card
      </code>
      
      , <code>
        border
      </code>
      
      , <code>
        text
      </code>
      
      , <code>
        highlighted
      </code>
      
      , <code>
        muted
      </code>
      
      , <code>
        dimmed
      </code>
      
      , <code>
        accent
      </code>
      
      , <code>
        codeBackground
      </code>
      
      , <code>
        accentBorder
      </code>
      
      , <code>
        band
      </code>
      
      ), or <code>
        false
      </code>
      
       for a mail that looks the same in every client
    </td>
  </tr>
</tbody>
</table>

Colors are hex. A single mail overrides the app's look with the same props on its root:

```vue
<WervtEmail subject="Your invoice" frame="none" :theme="{ accent: '#7c3aed' }" :brand="false">
```

### Header and footer

The `header` slot replaces what the band shows, the `footer` slot the whole footer, for an
imprint or an unsubscribe link:

```vue
<WervtEmail subject="This week in todos">
  <template #header>
    <img src="https://todos.lightdrop.cloud/mail/wordmark.png" alt="todos" height="28" />
  </template>

  <EmailText>…</EmailText>

  <template #footer>
    Todos GmbH, Musterstr. 1, 10115 Berlin ·
    <EmailLink :href="unsubscribeUrl">Unsubscribe</EmailLink>
  </template>
</WervtEmail>
```

### A layout of your own

`EmailDocument` at the root instead of `WervtEmail` gives a mail without wervt's header, footer
and frame: the document, subject, preview line, dark-mode setup and a centered column (`width`,
600 by default) to fill with your own tables. The building blocks still work inside it and follow
the theme; `useEmailTheme()` hands its tokens to components of your own.

```vue
<script setup lang="ts">
import { EmailButton, EmailDocument, EmailText } from '@wervt/nuxt/email'
</script>

<template>
  <EmailDocument subject="Your receipt" preview="Thanks for your order" :width="520">
    <table role="presentation" width="100%" cellpadding="0" cellspacing="0">
      <tr>
        <td style="padding: 32px; background: #052e16; color: #ffffff">Todos</td>
      </tr>
      <tr>
        <td style="padding: 32px">
          <EmailText>Thanks for your order.</EmailText>
          <EmailButton href="https://todos.lightdrop.cloud/orders/1">Track it</EmailButton>
        </td>
      </tr>
    </table>
  </EmailDocument>
</template>
```

Such a mail says nothing about who sent it unless you do: name the app and why the recipient got
the mail yourself.

## Languages

The frame's own texts ("Sent by …", "Secured by wervt") and `InviteEmail` come in English and
German. Pass `lang: 'de'` for German; the default is English. Your template's texts are yours, so
pick them by the same `lang`, for example with a small catalog from `@wervt/nuxt/i18n`:

```ts
import { defineMessages, translator } from '@wervt/nuxt/i18n'

const messages = defineMessages({
  en: { subject: 'Welcome to {app}' },
  de: { subject: 'Willkommen bei {app}' },
})
const t = translator(messages, 'de')
t('subject', { app: 'kontor' }) // "Willkommen bei kontor"
```

`defineMessages` checks at compile time that every language has every key of the English one.

## Sending

```ts
// server/api/invite.post.ts
import { sendMail } from '@wervt/nuxt/server'
import { defineEventHandler } from 'nuxt/server'
import Welcome from '../../emails/Welcome.vue'

export default defineEventHandler(async () => {
  await sendMail({
    to: 'ada@example.com',
    template: Welcome,
    props: { name: 'Ada', url: 'https://todos.lightdrop.cloud' },
  })
  return { ok: true }
})
```

`props` are the template's props. Mails come from `<app> <mail@lightdrop.cloud>`; set `replyTo` to
receive replies. `renderEmail(template, props)` returns `{ subject, html, text }` without sending.

`sendMail()` throws when the mail isn't sent, with the platform's status:

<table>
<thead>
  <tr>
    <th>
      Status
    </th>
    
    <th>
      
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        400
      </code>
    </td>
    
    <td>
      Invalid mail, e.g. not exactly one recipient
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        429
      </code>
    </td>
    
    <td>
      The app or the address is over its <a href="#limits">
        limit
      </a>
      
       for the last hour
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        502
      </code>
      
      , <code>
        503
      </code>
    </td>
    
    <td>
      The provider failed or mail isn't set up on the server
    </td>
  </tr>
</tbody>
</table>

## Limits

An app may send 100 mails per hour, and one address gets 20 per hour from all apps together.
Both count the last 60 minutes, failed sends included. Past a limit `sendMail()` throws with
status `429` until older mails drop out of the hour.

The defaults come from the control plane: `MAIL_LIMIT_PER_APP` and `MAIL_LIMIT_PER_RECIPIENT`
(`none` for no limit). Admins make an exception for a single app under **Mail** in the app's
settings in the dashboard, or with the CLI:

```bash
wervt mail-limits                                 # the defaults and every exception
wervt mail-limits todos                           # what one app is held to
wervt mail-limits todos --per-app 1000            # an exception, from the next mail
wervt mail-limits todos --per-recipient none      # no limit
wervt mail-limits todos --per-app default         # back to the server's default
```

An app with a `--per-recipient` of its own is counted apart for that address: what it sends
doesn't use up what other apps, the sign-in codes among them, may still send there. An exception
belongs to the app, not to its previews, and goes when the app is deleted.

## Local development

`nuxt dev` sends nothing: `sendMail()` prints the recipient, subject and plain text to the
terminal. Open `/_wervt/emails` to see every template in `emails/` rendered with its
`previewProps`, as HTML or (`?text`) plain text. New templates show up after restarting
`nuxt dev`.

## Privacy

wervt keeps a log of sent mail for 30 days: time, app, template name, status and a keyed hash of
the recipient's address, for the limits. Never the content or the address itself.


## Sitemap

See the full [sitemap](https://docs.lightdrop.cloud/sitemap.md) for all pages.
