Email

Your app sends three kinds of email from your own domain: sign-in codes, notifications your server sends a person, and your answers from the Inbox. Replies land in the Inbox.

An order ships, and your server tells the person:

import { gemmeinServer } from "@gemmein/sdk";
const server = gemmeinServer(process.env.GEMMEIN_SECRET_KEY);

await server.notify(order.ownerUserId, {
  subject: "Your poster is on its way",
  text: "It left the studio this morning. Reply to this email if it hasn't arrived by Friday.",
  key: `shipped:${order.id}`,
});
// → { sent: true, id, threadId, replyRail: true }

The sending domain

Add your domain on the Domains page and choose what it is for: your web app, email, or both. A domain for email gets all its records at once: SPF and DKIM for sending, and an MX for receiving. The page rechecks them until they are found. A mobile-only app has no web domain and can still have a sending one.

You choose where receiving lives when you add the domain:

• On mail.yourdomain (for shop.example.com, mail.shop.example.com). Sending and receiving share one record set, and the mail your domain already receives is untouched.
• On the domain itself, when its MX is Gemmein's.

Either way, people see your domain in the From line. Reply-To uses the domain too whenever a forward carries it there.

Sender addresses

Each kind of email leaves from its own address on your domain. The Domains page labels each one The word:

Each is a real address. Two kinds can never share one address; the dashboard refuses it. The defaults come from the word you gave the domain when you added it. The kind of a notify() sets only its cap, never its address.

The purchase email

When someone buys a product, through its Payment Link or a relay's fulfil_product, Gemmein emails the buyer once for that payment: Your <product> is ready, from your account address, with a link to your Library. The link is your app's verified web domain plus the Library path, never the file; the Library asks the buyer to sign in with the same email.

• On by default. Payments, under Products: Email buyers when they buy turns it off, and Library path sets where the link opens (/ until you set one).
• Sent only from your domain. With no verified sending domain, or no verified web domain to link, it is not sent; nothing leaves from a Gemmein address instead. Logs shows one row a day saying which is missing.
• Your own instead. Turn it off and send yours with notify(). Keys starting gemmein: are Gemmein's own and answer 400 reserved_key.

Development sends

In your cloud Development environment, every notify(), every relay email_person and every purchase email shares one daily budget: 20 a day per app and 50 a day per account. The next send answers 429 development_capped with resetAt. Sign-in codes are outside it, and Live has no such budget. Test volume locally with npx gemmein dev, which prints each send in the terminal and mails nothing.

Email templates

The emails Gemmein sends for your app can wear your own design. Write one HTML file per email in gemmein/emails/<name>.html with {{var}} placeholders, and the sign-in email's brand in gemmein/emails/sign-in.json. npx gemmein sync saves them in Development, and go-live and promote copy Development's templates into Live. npx gemmein dev uses the same files exactly as the cloud does and writes each email to gemmein/.data/mail. An email with no template sends in Gemmein's plain design.

• The sign-in brand. logoUrl is an https: image. When you save, Gemmein fetches it once (PNG, JPEG, GIF or WebP, up to 200 KB), keeps its own copy in your app's storage, and the email shows that copy, never your address. Changing the image at your address changes nothing until you save a changed sign-in.json. brandColour and backgroundColour are #rrggbb; a brand colour too light to read the code on is refused. appName (60 characters) is the header label when there is no logo; the sentence beside the code and the logo's description always use your app's real name. appName and greeting (120) are one line of plain text with no digits or numerals and nothing that looks like a web address. Every key is optional.
• What an HTML template may hold. Layout and text elements (tables, div, p, headings, links, images, lists) and CSS for colour, fonts, spacing, borders, sizes and alignment, as plain values. A <style> block is inlined onto your elements; @media rules stay when every selector names a class.
• What Gemmein removes. Scripts, forms, frames, embeds, SVG, media, <link>, <meta>, <base>, comments, event handlers, CSS url(), @import, @font-face, calc() and other CSS maths, positioning, transforms and negative values. Links are https:, mailto: or #; images are https: only; an address with a user part (https://a@b) is removed. Sync prints what was removed.
• Variables. Every value is HTML-escaped. {{body}} and {{content}} keep their line breaks. {{library_url}} is the only variable that can be a link's address.
• The footer. Your template renders inside its own box, and Gemmein adds its footer after it: your app's name and sending domain, and why the person received the email. The plain-text part is built from the result. None of these emails is marketing, so none has an unsubscribe line.
• Versions and limits. The cloud keeps each template's last 10 versions. Each app can save templates 60 times and preview them 120 times an hour (150 and 300 per account).
• Preview and test. npx gemmein emails preview <name> renders your local file with sample data into a page you open. npx gemmein emails test <name> sends one test of the synced template to the address you are signed in with. Tests count toward Development sends.

Send response

notify() answers { sent, deduped?, recorded?, id, threadId, replyRail }.

• deduped: true: the same key was sent before, and this is its answer again.
• recorded: false: the email was sent but not saved to the Inbox.
• replyRail: whether a reply can reach you now.
• Two sends with the same key at once: the second answers 409 in_flight.
• The caps answer 429 with resetAt.

The full response, with every code, is in the SDK reference.

The Inbox

Every send appears in the dashboard's Inbox as a conversation. Once receiving is verified, a person's reply lands in the same thread. Your answer goes out from support, so the whole exchange stays in one place for both of you.

Step-by-step: see the Inbox and Domains dashboard guides.

What happens if…

Sending

For notify(). A relay's email_person rides the same caps. The purchase email and Development's daily budget have their own sections: The purchase email and Development sends.

Templates

In the Inbox