# Welcome A welcome email template that names one next step and one place to get help. Table-based HTML for Outlook, a plain-text alternative, a preferences link, and the send call in TypeScript, Python, and curl. The welcome email is read once, in the thirty seconds after signup, by somebody who has already decided to try the thing. It does not need to sell. It needs to point at the one action that makes the product work for them. This one names that action, links the docs, and gives a real address to reply to. Everything else that products put in a welcome email, the feature grid, the founder photo, the discount, either belongs later in a sequence or nowhere. Topics: welcome email, onboarding, activation, first run. ## When it sends Once, after the address is verified and the account exists. Sending it before verification means welcoming an address that may never confirm. ## What you need - **An emails.sh API key**: Created in the dashboard, starting with esh_. It stays on your server. - **A sending domain**: Verified with three DNS records, or send from onboarding@emails.sh until yours is ready. - **One next step worth naming**: The action that correlates with people staying. Pick it from your own data, not from a list. - **A reply-to somebody reads**: A welcome email gets replies. Point them at a mailbox with a person behind it. ## Subject ```text Welcome to {{PRODUCT_NAME}} ``` ## HTML body ```html Welcome
Start here: {{NEXT_STEP}}.            

Welcome to {{PRODUCT_NAME}}, {{FIRST_NAME}}

Your account is ready. The one thing worth doing first is to {{NEXT_STEP}}.

Open {{PRODUCT_NAME}}

Button not working? Paste this into your browser:
{{DASHBOARD_URL}}

The quickstart walks the same path in about five minutes: {{DOCS_URL}}.

 

If you get stuck, reply to this email. It goes to {{SUPPORT_EMAIL}} and a person reads it.

You are getting this because you created a {{PRODUCT_NAME}} account.

Choose which emails you get: {{PREFERENCES_URL}}

``` ## Plain text body ```text Welcome to {{PRODUCT_NAME}}, {{FIRST_NAME}} Your account is ready. The one thing worth doing first is to {{NEXT_STEP}}. {{DASHBOARD_URL}} The quickstart walks the same path in about five minutes: {{DOCS_URL}} If you get stuck, reply to this email. It goes to {{SUPPORT_EMAIL}} and a person reads it. You are getting this because you created a {{PRODUCT_NAME}} account. Choose which emails you get: {{PREFERENCES_URL}} ``` ## Placeholders | Placeholder | What it is | Example | | --- | --- | --- | | {{PRODUCT_NAME}} | Your product, as the reader knows it. | Acme | | {{FIRST_NAME}} | What to call them. Fall back to "there". | Ada | | {{NEXT_STEP}} | The one action worth taking first, in a few words. | connect your first repository | | {{DASHBOARD_URL}} | Where that action starts. | https://acme.com/app | | {{DOCS_URL}} | The quickstart, not the docs home. | https://acme.com/docs/quickstart | | {{SUPPORT_EMAIL}} | The reply-to. A real mailbox with a person behind it. | support@acme.com | | {{PREFERENCES_URL}} | Where they choose which product emails they get. | https://acme.com/settings/email | ## How it works 1. **The address is verified** Only then is there somebody to welcome. 2. **You pick the next step** One action, chosen from what your retained accounts did first. 3. **You send this** With reply_to pointed at a mailbox somebody reads. 4. **They reply, sometimes** Answer those. The replies to a welcome email are the cheapest research you will get. ## Code ### TypeScript `npm install @emails.sh/sdk` ``` import { readFileSync } from 'node:fs'; import { Emailssh } from '@emails.sh/sdk'; const mail = new Emailssh({ apiKey: process.env.EMAILSSH_API_KEY }); // What changes per send. In your app these come from the row you just // wrote, not from literals. const vars: Record = { PRODUCT_NAME: 'Acme', FIRST_NAME: 'Ada', NEXT_STEP: 'connect your first repository', DASHBOARD_URL: 'https://acme.com/app', DOCS_URL: 'https://acme.com/docs/quickstart', SUPPORT_EMAIL: 'support@acme.com', PREFERENCES_URL: 'https://acme.com/settings/email', }; const fill = (body: string) => Object.entries(vars).reduce( (out, [name, value]) => out.replaceAll('{{' + name + '}}', value), body ); const { id } = await mail.send({ from: 'Acme ', to: ['ada@example.com'], subject: fill('Welcome to {{PRODUCT_NAME}}'), html: fill(readFileSync('email.html', 'utf8')), text: fill(readFileSync('email.txt', 'utf8')), replyTo: 'support@acme.com', tags: { type: 'welcome' } }); // Queued, not delivered. Ask for the id later, or take the webhook. console.log(id); ``` ### Python `pip install emailssh` ``` import os from emailssh import Emailssh mail = Emailssh(api_key=os.environ["EMAILSSH_API_KEY"]) # What changes per send. In your app these come from the row you just # wrote, not from literals. values = { "PRODUCT_NAME": "Acme", "FIRST_NAME": "Ada", "NEXT_STEP": "connect your first repository", "DASHBOARD_URL": "https://acme.com/app", "DOCS_URL": "https://acme.com/docs/quickstart", "SUPPORT_EMAIL": "support@acme.com", "PREFERENCES_URL": "https://acme.com/settings/email", } def fill(body: str) -> str: for name, value in values.items(): body = body.replace("{{" + name + "}}", value) return body with open("email.html", encoding="utf-8") as f: html = f.read() with open("email.txt", encoding="utf-8") as f: text = f.read() sent = mail.send( # from_ rather than from, which is a Python keyword. from_="Acme ", to=["ada@example.com"], subject=fill("Welcome to {{PRODUCT_NAME}}"), html=fill(html), text=fill(text), reply_to="support@acme.com", tags={"type": "welcome"}, ) # Queued, not delivered. Ask for the id later, or take the webhook. print(sent["id"]) ``` ### curl `Anywhere with curl and jq` ``` export EMAILSSH_API_KEY=esh_live_... # The API substitutes nothing, so fill the placeholders before you post. fill() { sed \ -e 's|{{PRODUCT_NAME}}|Acme|g' \ -e 's|{{FIRST_NAME}}|Ada|g' \ -e 's|{{NEXT_STEP}}|connect your first repository|g' \ -e 's|{{DASHBOARD_URL}}|https://acme.com/app|g' \ -e 's|{{DOCS_URL}}|https://acme.com/docs/quickstart|g' \ -e 's|{{SUPPORT_EMAIL}}|support@acme.com|g' \ -e 's|{{PREFERENCES_URL}}|https://acme.com/settings/email|g' "$1" } curl -sS https://emails.sh/v1/emails \ -H "Authorization: Bearer $EMAILSSH_API_KEY" \ -H "Content-Type: application/json" \ -d "$(jq -n \ --arg subject 'Welcome to Acme' \ --arg html "$(fill email.html)" \ --arg text "$(fill email.txt)" \ '{from: "Acme ", to: ["ada@example.com"], subject: $subject, html: $html, text: $text, reply_to: "support@acme.com", tags: {type: "welcome"}}')" ``` ## Questions ### Should the welcome email come from a person? A person as the display name and a monitored mailbox as the address works well. What does not work is a name with noreply@ behind it, which invites a reply into a black hole. ### Why only one link to the product? Because a welcome email with six equal links gets none of them clicked. The docs link is there in body text at a lower weight, which is a deliberate second place rather than a second button. ### Does a welcome email need an unsubscribe? It needs a way out of the sequence it starts. This one links preferences instead of a bare unsubscribe, so somebody can stop onboarding mail without also opting out of receipts and password resets. Docs: https://emails.sh/docs.md All templates: https://emails.sh/templates.md