NevarMail

Send each subscriber their own version of an email

Fill one template with each recipient's own data at send time, such as a personal offer or a newsletter written for the reader, under a use case your subscribers can unsubscribe from.

You can send every subscriber an email written for them. Your code holds what is different about each person. NevarMail holds the template and the use case. Each email is one POST /api/v1/email/send with four things: the use case, the recipient's email address, the template, and that person's values in variables. Because the use case is suppressable, NevarMail adds the unsubscribe footer and headers to every message and skips anyone who opted out. Your template and your request don't include either.

This page walks through two examples end to end: a personal offer, and a newsletter whose subject and content are chosen for each reader. Each one shows the template, the request, and the email the recipient gets.

How the pieces fit

PieceWhere it livesWhat it does
TemplateNevarMail (Templates)The subject, HTML and plain-text body, written once with {{placeholders}}
Use caseNevarMail (Use cases)Says why the email is sent. A suppressable use case adds the unsubscribe footer, the List-Unsubscribe headers and the opt-out check to every send
Per-person valuesYour appThe recipient's name, their offer, the stories picked for them. Sent as variables on each request

Before you start

  1. A suppressable use case. New use cases are suppressable unless you switch it off, and each project's default use case always is. Find the use case's id with GET /api/v1/use-cases, or use its slug in the use_case field instead of use_case_id.
  2. A postal address on the project. Every email under a suppressable use case carries it in the footer. Without one, the send is refused with 422 COMPLIANCE_ADDRESS_REQUIRED. Set it in Project Settings.
  3. A template. Create it in the app or with POST /api/v1/templates, and keep its id. Every send names it with templateId. A use case's Templates card lists templates already placed on that use case, but the send does not take its template from there.
  4. Test mode, if you are new. A new organization only sends to allow-listed addresses. See Test mode and safe send before you wonder where your first email went.

The request

POST /api/v1/email/send
{
  "to": "ada@example.com",
  "use_case_id": "<uuid>",
  "templateId": "<uuid>",
  "variables": { "first_name": "Ada", "offer": "..." }
}
FieldRequiredWhat it is
toYesThe recipient's email address. This is the only way to name a recipient today: one address, one email.
use_case_id or use_caseYes, unless your key is scoped to one projectThe use case this email is sent under, by id or by slug. Name it explicitly: the opt-out check then uses this use case's own list. With no use case named, the project's default is used and an opt-out from any list in the project blocks the send.
templateIdYesThe template to fill. Leave out subject, html and text: the template supplies all three.
variablesYes, for a template with placeholdersThis recipient's values, one key per placeholder.

cc and bcc are refused on a templated send (400 CC_BCC_NOT_SUPPORTED_FOR_TEMPLATE). Each email carries one person's unsubscribe link, so every recipient gets their own request. Of the other send fields, a templated send uses only from, fromName, replyTo, replyToName and emailType, as described in Send a transactional email. Anything else you add, such as metadata, priority or attachments, is ignored.

How variables are filled

Placeholders are read the same way in the subject, the HTML body and the plain-text body. How a value is written depends on the part (see the escaping rule below).

  • A placeholder reads one key. {{first_name}} is replaced with the value of variables.first_name. Spaces inside the braces are ignored, so {{ first_name }} works too.
  • Keys are flat. NevarMail does not look inside objects: {{user.name}} reads a key literally named "user.name", not variables.user.name. If you pass an object or an array as a value, it is written into the email as JSON. Name your variables first_name, offer_code and so on.
  • A missing value is not filled in. If a placeholder has no matching key, or its value is null, the placeholder itself is sent (without any spaces inside the braces), so the recipient reads Hi {{first_name}},. Variable declarations on the template, including required and default, are not applied at send time. Pass every variable the template uses on every request.
  • Values are HTML-escaped in the HTML body. In the HTML body, {{first_name}} writes &, <, >, " and ' as HTML entities. A name like Ada <3 shows as typed and cannot add markup to the email. Send plain values, not escaped ones: a value you escape yourself is escaped twice, and the recipient sees &amp;amp;.
  • Use three braces to insert HTML. {{{story_html}}} writes the value into the HTML body exactly as you pass it, for a piece of HTML your code built on purpose. NevarMail does not clean that HTML, so escape anything a person typed before you put it inside.
  • The text body and the subject are not escaped. The plain-text body gets each value as you pass it. In the subject, line breaks in a value are replaced by spaces, so the subject stays on one line.
  • There are no conditions or loops. A template cannot say "show this block only for VIP customers" or "repeat for each story". Give the template a fixed number of slots, as the newsletter below does. Or build a section in your code and pass it as one value in a {{{triple}}} placeholder, escaping anything a person typed.

To check a template before anyone gets it, render it with sample values. POST /api/v1/templates/:id/render takes the variables as the request body itself, not wrapped in a variables key, and returns the filled subject, HTML and text without sending anything. The footer is not part of the preview: it is added when the email is sent.

Example 1: a personal offer

Each customer gets a discount on a product they looked at, with their own code and expiry date.

The template

POST /api/v1/templates
{
  "name": "Personal offer",
  "subject": "{{first_name}}, {{discount}} off the {{product_name}} until {{expires_on}}",
  "htmlTemplate": "<html><body><p>Hi {{first_name}},</p><p>You looked at the <strong>{{product_name}}</strong> last week, so we saved you <strong>{{discount}} off</strong>.</p><p>Use code <strong>{{offer_code}}</strong> at checkout before {{expires_on}}.</p><p><a href=\"{{offer_url}}\">Claim your offer</a></p><p>The Acme Outfitters team</p></body></html>",
  "textTemplate": "Hi {{first_name}},\n\nYou looked at the {{product_name}} last week, so we saved you {{discount}} off.\n\nUse code {{offer_code}} at checkout before {{expires_on}}.\n\nClaim your offer: {{offer_url}}\n\nThe Acme Outfitters team",
  "variables": [
    { "name": "first_name", "type": "string", "required": true },
    { "name": "product_name", "type": "string", "required": true },
    { "name": "discount", "type": "string", "required": true },
    { "name": "offer_code", "type": "string", "required": true },
    { "name": "expires_on", "type": "string", "required": true },
    { "name": "offer_url", "type": "string", "required": true }
  ]
}

The send

curl -X POST https://app.nevarmail.com/api/v1/email/send \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "use_case_id": "YOUR_USE_CASE_ID",
    "to": "ada@example.com",
    "templateId": "YOUR_TEMPLATE_ID",
    "variables": {
      "first_name": "Ada",
      "product_name": "Ridgeline 40L Pack",
      "discount": "20%",
      "offer_code": "ADA-RIDGE-20",
      "expires_on": "November 15",
      "offer_url": "https://shop.example.com/offers/ADA-RIDGE-20"
    }
  }'

The response is the same as any send. When the provider returns a message id, id is that same value. Check status: a 200 with "status": "failed" means the provider refused the message and nothing went out.

{
  "data": {
    "id": "msg-abc123@yourdomain.com",
    "messageId": "msg-abc123@yourdomain.com",
    "status": "sent",
    "provider": "sendgrid",
    "sentAt": "2026-11-01T15:00:00.000Z"
  },
  "requestId": "req_..."
}

What Ada receives

Subject: Ada, 20% off the Ridgeline 40L Pack until November 15

HTML body, with the footer NevarMail added before </body> (line breaks added and inline styles shortened for reading):

<html><body>
<p>Hi Ada,</p>
<p>You looked at the <strong>Ridgeline 40L Pack</strong> last week, so we saved you <strong>20% off</strong>.</p>
<p>Use code <strong>ADA-RIDGE-20</strong> at checkout before November 15.</p>
<p><a href="https://shop.example.com/offers/ADA-RIDGE-20">Claim your offer</a></p>
<p>The Acme Outfitters team</p>
<div style="margin-top:32px; ...">
  <p>Acme Outfitters, 100 Main Street, Springfield, OR 97477</p>
  <p><a href="https://.../ada-unsubscribe-link" clicktracking="off" style="...">Unsubscribe</a></p>
</div>
</body></html>

Plain-text body:

Hi Ada,

You looked at the Ridgeline 40L Pack last week, so we saved you 20% off.

Use code ADA-RIDGE-20 at checkout before November 15.

Claim your offer: https://shop.example.com/offers/ADA-RIDGE-20

The Acme Outfitters team

--
Acme Outfitters, 100 Main Street, Springfield, OR 97477
Unsubscribe: https://.../ada-unsubscribe-link

The footer prints the project's postal address exactly as it is saved in Project Settings, so include your business name there if you want it in the footer. Click tracking is on for a suppressable use case, so the provider rewrites the links in the HTML part on the way out, and "Claim your offer" goes through the provider's tracking host. Links in the plain-text part are never rewritten, and neither is the unsubscribe link in either part. If open tracking is on for your provider account, the provider also adds a one-pixel image at the end of the HTML part. The unsubscribe link is signed for Ada and for this use case's list. Clicking it, or the one-click unsubscribe her mail client shows from the List-Unsubscribe headers, stops this use case's mail to her. Her next send under this use case is refused with 422 RECIPIENT_SUPPRESSED. See Unsubscribes and compliance.

Example 2: a newsletter written for each reader

Everyone gets the same weekly newsletter, but the subject names their city, the opening uses their own activity, the stories are the ones your app picked from what they read, and the event is near them.

The template

The template has a fixed number of slots: two stories and one event. Your app fills each slot for each reader.

POST /api/v1/templates
{
  "name": "Weekly trail report",
  "subject": "{{first_name}}, your {{city}} trail report for {{week_of}}",
  "htmlTemplate": "<html><body><h1>Your trail report, {{first_name}}</h1><p>You logged <strong>{{miles_logged}} miles</strong> this month. Here is what we picked for you this week.</p><h2>Picked for you</h2><h3><a href=\"{{story_1_url}}\">{{story_1_title}}</a></h3><p>{{story_1_summary}}</p><h3><a href=\"{{story_2_url}}\">{{story_2_title}}</a></h3><p>{{story_2_summary}}</p><h2>Near you in {{city}}</h2><p><a href=\"{{event_url}}\">{{event_name}}</a>, {{event_date}}</p><p>See you on the trail,<br>Acme Outfitters</p></body></html>",
  "textTemplate": "Your trail report, {{first_name}}\n\nYou logged {{miles_logged}} miles this month. Here is what we picked for you this week.\n\nPICKED FOR YOU\n\n{{story_1_title}}\n{{story_1_summary}}\n{{story_1_url}}\n\n{{story_2_title}}\n{{story_2_summary}}\n{{story_2_url}}\n\nNEAR YOU IN {{city}}\n\n{{event_name}}, {{event_date}}\n{{event_url}}\n\nSee you on the trail,\nAcme Outfitters",
  "variables": [
    { "name": "first_name", "type": "string", "required": true },
    { "name": "city", "type": "string", "required": true },
    { "name": "week_of", "type": "string", "required": true },
    { "name": "miles_logged", "type": "string", "required": true },
    { "name": "story_1_title", "type": "string", "required": true },
    { "name": "story_1_summary", "type": "string", "required": true },
    { "name": "story_1_url", "type": "string", "required": true },
    { "name": "story_2_title", "type": "string", "required": true },
    { "name": "story_2_summary", "type": "string", "required": true },
    { "name": "story_2_url", "type": "string", "required": true },
    { "name": "event_name", "type": "string", "required": true },
    { "name": "event_date", "type": "string", "required": true },
    { "name": "event_url", "type": "string", "required": true }
  ]
}

The send

curl -X POST https://app.nevarmail.com/api/v1/email/send \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "use_case_id": "YOUR_USE_CASE_ID",
    "to": "ada@example.com",
    "templateId": "YOUR_TEMPLATE_ID",
    "variables": {
      "first_name": "Ada",
      "city": "Portland",
      "week_of": "November 3",
      "miles_logged": "42",
      "story_1_title": "Five fall hikes under two hours from Portland",
      "story_1_summary": "Short loops with big views, picked because you saved three Columbia Gorge trails.",
      "story_1_url": "https://news.example.com/stories/fall-hikes-portland",
      "story_2_title": "How to pack a 40L bag for an overnight",
      "story_2_summary": "A checklist for the pack you have been looking at.",
      "story_2_url": "https://news.example.com/stories/pack-a-40l-bag",
      "event_name": "Saturday trail cleanup at Forest Park",
      "event_date": "November 8, 9 AM",
      "event_url": "https://events.example.com/forest-park-cleanup"
    }
  }'

Another reader gets the same template with their own values: their city in the subject, their miles, and the stories and event your app chose for them.

What Ada receives

Subject: Ada, your Portland trail report for November 3

HTML body, with the footer NevarMail added before </body> (line breaks added and inline styles shortened for reading):

<html><body>
<h1>Your trail report, Ada</h1>
<p>You logged <strong>42 miles</strong> this month. Here is what we picked for you this week.</p>
<h2>Picked for you</h2>
<h3><a href="https://news.example.com/stories/fall-hikes-portland">Five fall hikes under two hours from Portland</a></h3>
<p>Short loops with big views, picked because you saved three Columbia Gorge trails.</p>
<h3><a href="https://news.example.com/stories/pack-a-40l-bag">How to pack a 40L bag for an overnight</a></h3>
<p>A checklist for the pack you have been looking at.</p>
<h2>Near you in Portland</h2>
<p><a href="https://events.example.com/forest-park-cleanup">Saturday trail cleanup at Forest Park</a>, November 8, 9 AM</p>
<p>See you on the trail,<br>Acme Outfitters</p>
<div style="margin-top:32px; ...">
  <p>Acme Outfitters, 100 Main Street, Springfield, OR 97477</p>
  <p><a href="https://.../ada-unsubscribe-link" clicktracking="off" style="...">Unsubscribe</a></p>
</div>
</body></html>

Plain-text body:

Your trail report, Ada

You logged 42 miles this month. Here is what we picked for you this week.

PICKED FOR YOU

Five fall hikes under two hours from Portland
Short loops with big views, picked because you saved three Columbia Gorge trails.
https://news.example.com/stories/fall-hikes-portland

How to pack a 40L bag for an overnight
A checklist for the pack you have been looking at.
https://news.example.com/stories/pack-a-40l-bag

NEAR YOU IN Portland

Saturday trail cleanup at Forest Park, November 8, 9 AM
https://events.example.com/forest-park-cleanup

See you on the trail,
Acme Outfitters

--
Acme Outfitters, 100 Main Street, Springfield, OR 97477
Unsubscribe: https://.../ada-unsubscribe-link

Sending to all your subscribers

Send one request per subscriber from your own code. A sketch, with your own data in place of subscribers:

const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

for (const person of subscribers) {
  for (;;) {
    const res = await fetch(`${API_BASE}/api/v1/email/send`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${process.env.NEVARMAIL_API_KEY}`,
      },
      body: JSON.stringify({
        use_case_id: NEWSLETTER_USE_CASE_ID,
        to: person.email,
        templateId: TRAIL_REPORT_TEMPLATE_ID,
        variables: buildTrailReportVariables(person), // one plain value per placeholder
      }),
    });
    const body = await res.json();
    if (res.ok && body.data.status === "sent") break;
    // A 200 whose status is "failed" means the provider refused the message: nothing went out.
    const code = res.ok ? "PROVIDER_REFUSED" : body.code;
    // Opted out or otherwise suppressed: nothing was sent, move on to the next person.
    if (code === "RECIPIENT_SUPPRESSED") break;
    // API rate limit: wait as long as Retry-After says, then send this person again.
    if (code === "RATE_LIMITED") {
      await sleep(Number(res.headers.get("Retry-After") ?? 1) * 1000);
      continue;
    }
    // DAILY_RAMP_CAP (your sending warm-up) or anything else: stop here, and resume from this
    // person once the cause is fixed. Skipping ahead would hide a problem that refuses everyone,
    // such as a missing postal address.
    throw new Error(`send to subscriber ${person.id} refused: ${res.status} ${code}`);
  }
}
  • Opt-outs are handled for you. Anyone who unsubscribed from this use case, whose address bounced or complained, or who is otherwise suppressed in this project is refused with 422 RECIPIENT_SUPPRESSED and nothing is sent to them. Move on to the next person.
  • Only send to people who agreed to hear from you. NevarMail blocks people who opted out, but it does not check that a recipient ever subscribed. That part is up to your list.
  • Pace the loop. A send can be refused with 429 RATE_LIMITED by the API rate limit (wait for Retry-After) or with 429 DAILY_RAMP_CAP by your sending warm-up (the rest waits for tomorrow). See Why am I getting 429 errors?.
  • Send to a list is a different tool. POST /api/v1/email/send-to-list mails one subject and body, the same for everyone, to every member of a list. It takes no template and no variables, so it cannot personalize.
  • What is stored. Each send is logged with the recipient's address and the filled subject and body, as described in Your data and your recipients' data. Keep values out of variables that you would not want in that log.

When a send is refused

ResponseWhyFix
400 VALIDATION_ERRORto is not an email address, or a field has the wrong typeCheck the request against the request
400 CC_BCC_NOT_SUPPORTED_FOR_TEMPLATEThe request has cc or bccSend each recipient their own request
404 NOT_FOUNDNo template with that id that your key can readCheck templateId, and that the key can read that template's project
422 COMPLIANCE_ADDRESS_REQUIREDThe project has no postal address for the footerAdd it in Project Settings
422 RECIPIENT_SUPPRESSEDThe recipient opted out of this use case, bounced, complained, or is otherwise suppressed in this projectNothing to fix: skip them
429 RATE_LIMITED / 429 DAILY_RAMP_CAPThe API rate limit, or today's sending warm-up allowanceWait for Retry-After, or send the rest tomorrow
422 TEST_MODE_RECIPIENT_NOT_ALLOWEDYou are in test mode and the address is not allow-listedSee Test mode and safe send

For anything else, start at Why didn't my email send?.

Can NevarMail send each subscriber a different version of the same email?
Yes. Write the email once as a template with placeholders, then send one request per subscriber with POST /api/v1/email/send, naming the use case, the recipient's email address, the template and that person's values in variables. NevarMail fills the subject, HTML and plain-text body for each recipient.
Do I have to add an unsubscribe link to a personalized marketing email?
No. Send it under a suppressable use case and NevarMail adds the unsubscribe footer with your postal address and the List-Unsubscribe headers to every message, and refuses sends to anyone who opted out of that use case.
What happens if I forget to pass a variable?
The placeholder is sent in the email, so the recipient sees text like {{first_name}}. Pass every variable the template uses on every send, and preview with POST /api/v1/templates/:id/render first.
Does NevarMail escape the values I pass in variables?
Yes, in the HTML body. A {{key}} placeholder there writes &, <, >, " and ' as HTML entities, so send plain values and do not escape them yourself. To insert HTML your code built on purpose, use three braces, {{{key}}}: that value is written exactly as you pass it. The plain-text body is not escaped, and in the subject, line breaks in a value become spaces.
Can I personalize a send-to-list email?
Not today. POST /api/v1/email/send-to-list sends the same subject and body to every member of a list. To give each subscriber their own content, send one templated request per subscriber.

On this page