DEV Community: Lunea Labs

How to send license key emails from your SaaS

Lunea Labs — Tue, 27 Oct 2026 19:56:56 +0000

A license key email is the message your app sends right after a purchase, with the key the buyer needs to activate your software. Send it from your server when your payment provider confirms the payment, not from the checkout page. Put the key in the body (never the subject line), in a format that is easy to copy. Add the product, the number of seats, the download links and a way to find the key again. Send it from your own authenticated domain, record that you sent it so it never goes out twice, and keep promotions out of it.

What a license key email must contain

Buyers' "where is my key?" threads show what goes wrong: keys land in spam, addresses are mistyped, keys get lost. A good email prevents those questions. Include:

The key itself, on its own line, in a monospace font, with nothing else on that line.
What it covers: product name, plan, number of seats, and the expiry or renewal date if there is one.
How to activate it: two or three short steps, or one link to your activation docs.
Download links, if the product is installed software.
Where to find the key later: a link to the account or billing page where the key is also shown.
Who to contact: a reply-to address that a person reads, not no-reply@.
An order reference, so support can find the purchase quickly.

Sketch's keys start with SK3, so buyers can search their inbox for it. A fixed prefix on your keys saves support tickets.

When to send it: after the payment is confirmed

Send the email from your backend when your payment provider confirms the payment. With Stripe Checkout, that is the checkout.session.completed webhook (a webhook is an HTTP request the provider sends to your server when something happens), plus checkout.session.async_payment_succeeded for slower payment methods such as bank transfers.

Two rules from Stripe's fulfilment guide apply to every provider:

Don't rely on the thank-you page. A buyer can pay and lose their connection before it loads. The webhook goes to your server directly and is retried if delivery fails.
Expect to be called more than once. Stripe says your fulfilment function "might be called multiple times, possibly concurrently, for the same Checkout Session." Send on every call and some buyers get two keys.

So: confirm the payment, assign the key, save it with the order, then send the email and record the send. If the email fails, retry it without creating a new key.

From the LuneaMail team: We built LuneaMail because we needed to send highly customised emails from our own product, and there was no simple way to do it. With Gmail we ended up rendering templates in Google Sheets and trying plugins, and the result was far from what we wanted. HubSpot took many steps to send one styled email, and its templates limited what we could build. So we built the tool we wanted as developers: paste your HTML, make it dynamic with Handlebars, send your data as JSON, and the email goes out looking exactly as designed. A license key email is that idea in its simplest form: one person, one moment, their own data.

A license key email template you can copy

Replace the parts in {{double braces}} with your data. The same names are used in the API example below.

Subject: Your {{product}} license key

Preheader (the grey preview text after the subject in most inboxes): Your key, {{seats}} seats, and how to activate it.

Body:

Hi {{firstName}},

Thanks for buying {{product}}. Here is your license key:

{{licenseKey}}

It includes {{seats}} seats.

To activate: open {{product}}, go to Settings › License, and paste the key. (Use your product's real steps.)

Download: macOS · Windows

You can see this key at any time in your account: {{accountUrl}}

Order reference: {{orderId}}

Questions? Reply to this email and a person will answer.

Keep the plain-text version the same. For several keys in one order, repeat a block with {{#each}}, as the download links do below.

Send it with one API call

With LuneaMail's transactional API, the template lives in your workspace, designed in the visual builder or written in HTML, and your server sends only the data. Variables use Handlebars: {{licenseKey}} inserts a value, {{#if seats}}…{{/if}} shows a section only when the data has it, and {{#each downloads}}…{{/each}} repeats a block for each item in a list. In the visual builder, a section's "Show this section" condition becomes the same {{#if}} block.

The template body:

<p>Hi {{firstName}}, thanks for buying {{product}}.</p>
<p>Your license key: <strong>{{licenseKey}}</strong></p>

{{#if seats}}
  <p>It includes {{seats}} team seats.</p>
{{/if}}

{{#each downloads}}
  <a href="{{url}}">Download for {{name}}</a>
{{/each}}

<p>Find this key any time in <a href="{{accountUrl}}">your account</a>.</p>
<p>Order reference: {{orderId}}</p>

The call from your fulfilment code (Node.js):

async function sendLicenseEmail(order) {
  const res = await fetch("https://app.luneamail.com/api/v1/send", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.LUNEAMAIL_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      templateId: process.env.LICENSE_TEMPLATE_ID,
      to: order.email,
      subject: "Your {{product}} license key",
      data: {
        firstName: order.firstName,
        product: "Pro",
        licenseKey: order.licenseKey,
        seats: order.seats,
        orderId: order.id,
        accountUrl: "https://example.com/account/licenses",
        downloads: [
          { name: "macOS", url: "https://example.com/download/mac" },
          { name: "Windows", url: "https://example.com/download/windows" },
        ],
      },
    }),
  });

  if (res.status === 202) {
    const { messageId } = await res.json(); // { status: "queued", messageId }
    await markLicenseEmailSent(order.id, messageId);
    return;
  }

  const { error, message } = await res.json();
  throw new Error(`License email not sent: ${error}: ${message}`);
}

The subject takes the same variables as the body. to is one address per call.

What the API can answer

Status	Error	What it means	What to do
202	–	Accepted and queued	Save the `messageId` with the order
400	`MISSING_VARIABLE`	The template uses a variable you didn't send	Fix the data; nothing was sent
400	`INVALID_TEMPLATE`	Wrong template ID, or the template is empty	Check the ID
401	`UNAUTHORIZED`	Missing or wrong API key	Check the key
422	`SUPPRESSED`	The address bounced or reported spam before	Don't retry; show the key in the app and ask for another address
429	`RATE_LIMITED`	More than 600 sends a minute on this key	Wait for the `Retry-After` header
429	`QUOTA_EXCEEDED`	Your monthly email allowance is used up	Top up or upgrade
502	`SEND_FAILED`	The send failed downstream	Retry later

MISSING_VARIABLE is the useful one. Variables outside {{#if}} and {{#each}} are required, so if your code forgets licenseKey, the API refuses instead of sending "Your license key:" with nothing after it. More on the developers page.

Don't send it twice

With two webhook deliveries at the same moment, "check if sent, then send" can pass twice. Claim the order first with one atomic update, for example UPDATE orders SET license_email = 'sending' WHERE id = $1 AND license_email IS NULL, and only send if a row changed.

Format the key so people can copy it

Monospace, on its own line, with no full stop after it to copy by mistake.
Groups with dashes, like ABCD-1234-EFGH, so it can be read aloud to support.
No look-alike characters in your key alphabet: 0 and O, 1, I and l. Someone will type it from a screenshot.
Accept the key with or without dashes and spaces when activating. Pasted text often has a trailing space.

Security: what not to put in the email

A license key is a credential: whoever has it can use what the buyer paid for. Email is the expected way to deliver it, so limit the damage.

Not in the subject line. Subjects appear in phone notifications, on lock screens and in inbox lists. "Your Pro license key" is fine; the key itself is not.
Show the key in the account too, and let the owner replace it. A leaked email then has a fix.
For high-value keys, send a link instead. The email says "Your key is ready" and links to the account page behind a login.
Don't log the request body. If your app logs every outgoing API call, your logs now hold every key you've sold.
Resend only to the address on the order. A "send my key again" form that accepts any address lets anyone collect keys.

Make sure it arrives

A key in the spam folder becomes a support ticket, or a refund request.

Send from your own domain, authenticated. Gmail requires SPF or DKIM from every sender (SPF and DKIM are DNS records that prove a mail server may send for your domain). In LuneaMail you add your domain and its DKIM records once. Until the domain is verified, mail goes out from LuneaMail's address with replies going to yours.
Use a reply-to someone reads. Buyers reply to license emails with real problems.
Handle bounces. If an address bounced before, the API returns SUPPRESSED and sends nothing. Show the key in the account too, so a bad address never blocks a buyer.

Transactional, not marketing

A license key email is transactional: it delivers what someone just paid for. The FTC's CAN-SPAM guide counts messages that "deliver goods or services as part of a transaction that the recipient already has agreed to" as transactional, so you need no marketing consent and no unsubscribe link. In LuneaMail, people who unsubscribed from your newsletter still get their license emails.

The catch: the FTC judges mixed emails by their primary purpose. A subject that reads like an ad, or a promotion above the key, can make the whole email commercial. So no discount banner, no newsletter sign-up, no "you might also like". Upsell in a separate marketing email, to people who agreed to receive one.

Resends, wrong addresses and refunds

Resend: add an "Email my key again" button in the account. It calls the same function with the same template and the same key.
Wrong address: buyers mistype emails. Let support change the address on an order, then resend. The key should never be emailed to the new address without that check.
Refund or chargeback: revoke the key on your license server. A short, factual notice is transactional too.

Checklist

[ ] Email sent from the payment webhook, not the thank-you page
[ ] One email per order, even if the webhook arrives twice
[ ] Key in the body, monospace, on its own line; not in the subject
[ ] Product, plan, seats, activation steps and order reference
[ ] Link to the account page where the key is also shown
[ ] A reply-to address a person reads
[ ] Sent from your own domain with SPF and DKIM
[ ] No promotions anywhere in the email
[ ] Resend button that only sends to the order's address
[ ] Key revoked on refund

Common mistakes

Sending from the checkout success page. Some buyers never reach it.
No idempotency. Duplicate webhooks mean duplicate keys.
The key in the subject line. Visible on every lock screen.
A blank key. A missing variable rendered as an empty string. Fail loudly instead.
An upsell above the key. It can turn a transactional email into a marketing one.
The key only in email. Lose the email and the buyer has to contact support.

Sending license keys with LuneaMail

LuneaMail's transactional API is one POST /send call with a template ID, an address and your data. Your team designs the template in the same editor as your newsletters, so license emails match your brand without a second tool, and they use the same monthly allowance as campaigns on every plan, including Free (pricing). The same pattern works for other app email; see our guide to team invite emails.

Originally published on the LuneaMail blog.

Gmail and Yahoo bulk sender requirements for your app emails

Lunea Labs — Mon, 26 Oct 2026 20:23:11 +0000

Gmail and Yahoo have applied stricter rules to bulk senders since February 2024. Google calls you a bulk sender if you send close to 5,000 or more messages to personal Gmail accounts in 24 hours. Bulk senders must:

authenticate with SPF and DKIM, and publish a DMARC record (p=none is the minimum),
make sure the visible From domain aligns with the SPF or DKIM domain,
add one-click unsubscribe to marketing emails and honor opt-outs within two days,
keep the spam complaint rate below 0.3%, and aim for under 0.1%.

Smaller senders still need SPF or DKIM, valid reverse DNS, TLS and a spam rate below 0.3%.

This article explains each rule as Google and Yahoo state it today, with links. It also covers what the rules mean for app emails like password resets and receipts, and a few launch problems we hit at LuneaMail that no rule mentions.

Who counts as a bulk sender

Google's sender guidelines FAQ defines a bulk sender as one that "sends close to 5,000 messages or more to personal Gmail accounts" within 24 hours. Two details in that FAQ matter for startups:

"Messages sent from the same primary domain count toward the 5,000 limit." Your app emails, newsletter and product updates all add up if they share example.com, even when they use different subdomains.
"Senders who meet the above criteria at least once are permanently considered bulk senders." One busy launch day is enough. You don't go back.

Yahoo's Sender Hub does not publish a volume number. Treat the bulk rules as your baseline from the first email. They are not hard to meet, and an early-stage SaaS can cross the line in a single launch.

The rules side by side

These are the requirements as Google's email sender guidelines and Yahoo's best practices state them on 24 October 2026.

Requirement	All senders	Bulk senders
Authentication	SPF or DKIM	SPF and DKIM
DMARC	Not required	Required; policy can be `p=none`
From alignment	Not required	From domain aligned with the SPF or DKIM domain
Forward and reverse DNS (PTR)	Required	Required
TLS connection	Required (Google)	Required (Google)
Message format	RFC 5322 (Yahoo also lists RFC 5321)	Same
Spam rate	Below 0.3%	Below 0.3%
One-click unsubscribe	Not required	Marketing and subscribed messages
Honor unsubscribes	Not stated	Within 2 days (Yahoo), 48 hours (Google)

A few terms. PTR (reverse DNS) maps the sending server's IP address back to a name. Your email provider handles PTR and TLS for you, so as a SaaS team you mostly own the other rows. Alignment means the domain people see in the From address matches the domain that passed SPF or DKIM. Yahoo says "relaxed alignment is acceptable", so mail.example.com can align with example.com. Google judges it at the organizational-domain level and only needs SPF or DKIM to align, not both.

Google adds one more DKIM detail: sending to personal Gmail accounts "requires a DKIM key of 1024 bits or longer". Any current ESP meets this.

If you haven't set up the records yet, our SPF, DKIM and DMARC setup guide walks through it with example DNS records.

What the rules mean for app emails

Your SaaS sends two kinds of email:

Transactional: password resets, verification links, receipts, license keys, security alerts. One person triggered them.
Marketing or subscribed: newsletters, product announcements, onboarding drips, promotions.

The authentication rules, the alignment rule and the spam-rate limit apply to both. The volume counts both too.

The unsubscribe rule is different. Google's FAQ says: "One-click unsubscribe is required only for marketing and promotional messages." It gives password resets and reservation confirmations as examples of transactional messages that don't need it. So your password reset email doesn't need an unsubscribe header. Your weekly product update does.

Be honest about the line. A "receipt" that is half promotion is a marketing email. If you're unsure, add the header. It costs nothing.

One-click unsubscribe (RFC 8058)

One-click unsubscribe means the mail app shows an "Unsubscribe" button next to your sender name. One click, no login, no "are you sure" page. It works through two email headers defined in RFC 8058:

List-Unsubscribe: <https://example.com/unsubscribe/one-click/abc123>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

The URL must be https. When the person clicks, their mail provider sends a POST request to it, with no cookies or login. Your server must unsubscribe them from that request alone. RFC 8058 says the URL should contain a hard-to-forge identifier, so use a unique token per recipient, not their email address in plain text.

Google also requires "a clearly visible unsubscribe link in the message body". The header and the link work together. Yahoo calls the RFC 8058 POST method "highly recommended" and asks you to honor unsubscribes within 2 days. Google recommends 48 hours.

According to Google's FAQ, a missing one-click header does not cause automatic rejection. But people who can't unsubscribe easily press "Report spam" instead, and that hurts the next rule.

Spam rate: aim for 0.1%, never reach 0.3%

The spam rate is the share of your emails that recipients mark as spam. Google says to "keep spam rates reported in Postmaster Tools below 0.10% and avoid ever reaching a spam rate of 0.30% or higher". That is 1 complaint per 1,000 emails as a target, and 3 per 1,000 as the hard limit. Google calculates it daily. Yahoo calculates its rate "based on mail delivered to the inbox".

To watch your Gmail numbers, add your domain to Google Postmaster Tools.

What keeps the rate low:

Email only people who signed up, and send what they signed up for.
Make unsubscribing easier than reporting spam.
Stop emailing addresses that bounce or complain. Automatically, forever.
Don't judge engagement by open rates alone (see below).

Opens can lie

Apple Mail Privacy Protection loads every email automatically, including the tracking pixel. Those "opens" are not people reading. If you count them, inactive contacts look engaged and you keep emailing them, which pushes up complaints. When we built LuneaMail's analytics, we stored those opens separately as machine opens. We also stopped counting clicks on unsubscribe and other footer links as engagement. A click on "Unsubscribe" is not interest.

What happens if you don't comply

Google's FAQ says: "Starting November 2025, Gmail is ramping up its enforcement on non-compliant traffic." Enforcement is "gradual and progressive", and faster for new domains. In practice:

Temporary errors (4.7.x): Gmail delays the message. The error code tells you which requirement failed.
Permanent errors (5.7.x): the message is blocked.
Messages may also go straight to spam.

If your spam rate spikes, Google only offers mitigation once it stays below 0.3% for 7 consecutive days. Microsoft announced its own requirements for high-volume senders to Outlook in 2025. Read that post too if many of your users have Outlook.com addresses.

The launch problem no rule mentions: your provider's plan

You can pass every rule above and still send nothing. This happened to us during LuneaMail's launch.

We sent through SendGrid. The account was on a free trial. The trial ended without us noticing, and SendGrid started refusing mail with a "Maximum credits exceeded" error. Every email stopped, including the ones that matter most: password resets and sign-up verification links. That means a new user can't confirm their account, and a locked-out user can't get back in.

Before launch, check:

[ ] Your email provider's plan, its monthly and daily limits, and when any trial ends
[ ] What happens at the limit: a hard stop or overage billing
[ ] An alert when sending fails, not just when the provider emails you
[ ] That a password reset and a sign-up email arrive in a real Gmail and Yahoo inbox

From the LuneaMail team: When you build your own email sending, you also take on the job of making sure it actually gets delivered. Authentication, unsubscribes, spam rates and your provider's limits all become your problem, and you usually find a gap only when someone doesn't get an email they were waiting for. That's a huge undertaking for a team that just wants to send a few branded emails, and a large part of why we built LuneaMail.

Common mistakes

Sending from @gmail.com through an ESP. Google's guidelines say "Don't impersonate Gmail From: headers" and point to Gmail's DMARC quarantine policy. Use an address on your own domain.
Unsubscribe link with no header. The body link alone doesn't give the one-click button.
An unsubscribe page that needs a login. It is not one click, and people report spam instead.
Treating onboarding drips as transactional. If it promotes features or upgrades, it's marketing.
Not suppressing bounces and complaints. Every repeat send to a complainer adds to your spam rate.
Trusting open rates. Apple's automatic opens make dead lists look alive.

How LuneaMail handles this

We built these rules into LuneaMail's send path, so a campaign can't go out without them:

Every campaign and automation email carries List-Unsubscribe and List-Unsubscribe-Post: List-Unsubscribe=One-Click headers, plus a visible unsubscribe link in the footer.
The footer includes your postal address. LuneaMail won't send a campaign until you add one in Settings › Brand kit.
From addresses at free mailbox providers like Gmail, Yahoo or Outlook are refused for campaigns. You send from your own domain, which you can authenticate in Settings › Domains.
The workspace owner must confirm their email address before sending to a list.
Unsubscribes, bounces and spam complaints are suppressed automatically.
Apple's automatic opens are counted as machine opens, not real opens, and footer-link clicks don't count as engagement.

App emails like receipts and license keys go through the same authenticated domain with the transactional email API. See the features page and the developer docs for details.

Originally published on the LuneaMail blog.