Skip to content
Groundmail

Free email template

Usage alert email template

Warns before a plan limit is hit, with a progress bar and the reset date. Free and MIT-licensed, in React Email, MJML, HTML and plain text, with light and dark mode built in.

Get the codeView on GitHub
  • MIT license
  • Works with any email provider
  • Light and dark mode

What every usage alert email needs.

The template covers five. Point 5 depends on your plan rules, so add a line saying what happens at the limit.

  1. Before the limit, not at it

    Warn at a threshold like 80%, while there's still time to act. Send each alert once per billing period, not on every request after it.

  2. The real numbers

    Used and limit, with the metric named the way your pricing page names it. "80,000 of 100,000 monthly API requests" beats "you're nearly out".

  3. A bar people read at a glance

    The template's progress bar shows how close they are before they read a word.

  4. When it resets

    If the reset is two days away, waiting may be the right answer. Give people the date so they can decide.

  5. What happens at 100%

    Does the service stop, slow down or bill for extra use? Say which. People plan differently for each.

  6. A way to change these alerts

    Heavy users hit thresholds every month. Let them pick their own, or turn them off, from account settings.

The code. Copy the format your stack uses.

Change the brand name, logo and colors once in theme.ts and every template follows.

import * as React from 'react'
import { Button, Details, Layout, Meter, P, Small, Title } from '../../components'
import type { TemplateMeta } from '../../components/meta'
import { plainText, textDetails } from '../../components/text'

export type UsageAlertProps = {
  name: string
  metric: string
  usagePercent: string
  used: string
  limit: string
  resetsOn: string
  upgradeUrl: string
}

export const meta: TemplateMeta = {
  name: 'Usage alert',
  description: 'Warns before a plan limit is hit, with a progress bar and the reset date.',
  group: 'Billing',
  subject: "You've used {{usage_percent}}% of your {{metric}}",
}

export default function UsageAlert(props: UsageAlertProps) {
  const { name, metric, usagePercent, used, limit, resetsOn, upgradeUrl } = props
  return (
    <Layout
      preview={`You've used ${used} of ${limit} ${metric}. Your limit resets on ${resetsOn}.`}
      footerNote="You're receiving this because usage alerts are on for your account."
    >
      <Title>
        You've used {usagePercent}% of your {metric}
      </Title>
      <P>Hi {name}, you're getting close to your plan's limit for this billing period.</P>
      <Meter percent={usagePercent} />
      <Details
        rows={[
          ['Used', `${used} of ${limit}`],
          ['Resets on', resetsOn],
        ]}
      />
      <P>To avoid interruptions, upgrade your plan before you reach the limit.</P>
      <Button href={upgradeUrl}>Upgrade plan</Button>
      <Small style={{ margin: 0 }}>You can change when you get these alerts in your account settings.</Small>
    </Layout>
  )
}

UsageAlert.PreviewProps = {
  name: 'Ada',
  metric: 'monthly API requests',
  usagePercent: '80',
  used: '80,000',
  limit: '100,000',
  resetsOn: 'November 1, 2026',
  upgradeUrl: 'https://example.com/billing/plans',
} satisfies UsageAlertProps

export function text(props: UsageAlertProps) {
  const { name, metric, usagePercent, used, limit, resetsOn, upgradeUrl } = props
  return plainText(
    `You've used ${usagePercent}% of your ${metric}`,
    `Hi ${name}, you're getting close to your plan's limit for this billing period.`,
    textDetails([
      ['Used', `${used} of ${limit}`],
      ['Resets on', resetsOn],
    ]),
    `To avoid interruptions, upgrade your plan before you reach the limit: ${upgradeUrl}`,
    'You can change when you get these alerts in your account settings.',
  )
}

usage-alert.tsx, 70 lines, shown in full (scroll inside the panel). Typed props. Copy it with theme.ts and components/ from the repo. View on GitHub

Send it with Groundmail

Create the template in your account once, then send it by alias from your app.

1Terminal
npx -y --package=groundmail-cli -- groundmail templates push templates/usage-alert/usage-alert.html \
  --alias usage-alert \
  --name "Usage alert" \
  --subject "You've used {{usage_percent}}% of your {{metric}}" \
  --text templates/usage-alert/usage-alert.txt \
  --publish
2Node.js
import { Groundmail } from 'groundmail'

const groundmail = new Groundmail(process.env.GROUNDMAIL_API_KEY!)

await groundmail.emails.send({
  from: 'Acme <noreply@yourdomain.com>',
  to: 'ada@example.com',
  template: {
    id: 'usage-alert',
    variables: {
      name: 'Ada',
      metric: 'monthly API requests',
      usage_percent: '80',
      used: '80,000',
      limit: '100,000',
      resets_on: 'November 1, 2026',
      upgrade_url: 'https://example.com/billing/plans',
    },
  },
})

The CLI command and the Node.js send from the template's README, which also has Python, PHP and cURL. View on GitHub

Subject lines

The number is the news. Put it first and name the limit it's about.

  • You've used {{usage_percent}}% of your {{metric}}DefaultThe number and the metric, readable from the notification.
  • Acme: {{usage_percent}}% of your {{metric}} usedGoodBrand first, for people who use several metered services.
  • You're close to your Acme {{metric}} limitGoodFor a second alert, when the exact figure matters less than the warning.
  • Upgrade now and save 20%!AvoidA usage alert is a service message. Turning it into a sales pitch makes it marketing, to people and to filters.

An alert after the limit is an outage report

Usage alerts are time-sensitive. One that's delayed or filtered arrives after the service has already stopped, which is the moment it was meant to prevent.

Google, Yahoo and Microsoft sender rules →
  • Keep it on a transactional stream, apart from newsletters and marketing.
  • Send from your own domain with SPF, DKIM and DMARC set up.
  • Send once per threshold per period, so a busy account doesn't get the same alert a hundred times.
  • Groundmail sends this template by alias from your own domain, on our own mail servers. Send it with Groundmail

More billing templates

All email templates →

Questions

Is it free to use?

Yes. The templates are MIT-licensed: use them in commercial products and change them however you like.

Do I need Groundmail to use it?

No. The HTML and text files use plain placeholders that work with most providers' template engines and with Handlebars or Mustache. Sending through Groundmail just saves a step.

Does it work in dark mode and Outlook?

Yes. The full HTML file carries dark-mode styles for Apple Mail and Outlook.com, and the extra markup desktop Outlook needs to draw the button.

How do I change the colors and logo?

Edit theme.ts once (name, logo, address and colors for light and dark) and rebuild. Every template in the set picks it up.