DEV Community

Qasim
Qasim

Posted on

Send templated email with the Nylas Templates API

#email #api #devtools #productivity

Every app sends the same handful of emails over and over: the welcome message, the password reset, the follow-up, the receipt. The lazy way is to build each one as a string in your code, which means a copy change is a code change, marketing can't touch it, and the same wording drifts out of sync across three different send sites. Hosted templates fix that by pulling the copy out of your code into a named, reusable resource with variables you fill at send time.

This post covers templates from two angles: the HTTP API your backend calls, and the nylas CLI for quick sends from the terminal. One thing to get straight up front, which trips people up: the API's hosted templates and the CLI's templates are two different stores, and a later section spells out exactly how they differ. I work on the CLI, so the terminal commands below are the ones I reach for when testing.

What a hosted template is

A hosted template is a reusable email with a name, a subject, an HTML body, and variables, the placeholders you substitute with real values each time you send. You write {{name}} or {{topic}} in the subject or body, and at send time you supply a variables object that fills them in. The copy lives in one place, so changing the wording is one update rather than a hunt through your codebase.

Hosted templates come in two scopes. Application-level templates live at /v3/templates and are shared across your whole application; grant-level templates live at /v3/grants/{grant_id}/templates and belong to one connected account. This post uses application-level templates, which is the common case for shared copy, and the two work the same way apart from the path and who can see them. Either way, a template is shared infrastructure for outbound copy, not a draft that lives in one specific mailbox.

Create a hosted template

Creating a template is a POST /v3/templates with a name, subject, and body, where the subject and body can include {{variable}} placeholders. The body is HTML, so a branded message with formatting and links lives in the template the same way a plain one does. The response returns the template with its ID, which you use to send, render, or update it later.

curl --request POST \
  --url "https://api.us.nylas.com/v3/templates" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Follow-up",
    "subject": "Following up on {{topic}}",
    "body": "<p>Hi {{name}},</p><p>Wanted to follow up on {{topic}}.</p><p>Best,<br>{{sender}}</p>",
    "engine": "mustache"
  }'
Enter fullscreen mode Exit fullscreen mode

The engine is mustache, the templating engine that interprets the {{variable}} syntax. Because the body is HTML, write it as HTML rather than plain text with newlines, and let the markup carry the structure. The variables work in both the subject and the body, so a single template can personalize the line a recipient sees in their inbox list as well as the message itself.

Send from a hosted template

Once a template exists, sending from it means referencing it on a POST /v3/grants/{grant_id}/messages/send request. You add a template object with the template's id and a variables map that fills the placeholders, and Nylas renders the final subject and body before the message goes out. The send still runs through the grant's own mailbox, so the message lands in the recipient's inbox as ordinary mail from that account, not anything that reads as auto-generated.

curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/messages/send" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "to": [{ "email": "client@example.com" }],
    "template": {
      "id": "<TEMPLATE_ID>",
      "variables": { "name": "Alex", "topic": "the proposal", "sender": "Sam" }
    }
  }'
Enter fullscreen mode Exit fullscreen mode

The template only shapes the content; delivery is the same send path as a hand-written message. Because the template is referenced by a stable ID, your application code holds just that ID, not the copy, so the wording can change underneath it without a deploy.

From the terminal, nylas email send sends a hosted template directly: pass --template-id and the variables as --template-data JSON. The --template-scope flag (app or grant, defaulting to app) and --template-grant-id pick which of the two scopes the template lives in. This is the CLI surface for the same hosted templates, distinct from the local templates command covered later.

nylas email send \
  --to client@example.com \
  --template-id <TEMPLATE_ID> \
  --template-data '{ "name": "Alex", "topic": "the proposal", "sender": "Sam" }'
Enter fullscreen mode Exit fullscreen mode

Missing variables: strict is the default

A template is only as good as the data you feed it, and the failure mode is an email that goes out with a raw {{name}} still in the body because you forgot a variable. The template object's strict flag guards against this, and the important detail is that strict is on by default: if the template contains a variable you didn't provide in variables, the send returns an error rather than delivering a half-filled message.

That default is the safe one, so most of the time you do nothing and a missing variable fails loudly in development instead of reaching a customer. You opt out by setting strict to false, which tells Nylas to render an unprovided variable as an empty string and send anyway. Reach for strict: false only when a blank is genuinely acceptable, like an optional middle name, and leave the default in place everywhere else. On the CLI it's the --template-strict flag on nylas email send, which also defaults to on.

Preview before you send

Sending a template to a real recipient just to see how it renders is a bad way to find a typo, so render it first. POST /v3/templates/{template_id}/render returns the rendered subject and body with your variables substituted, without sending anything, so you can show a preview in your own UI or assert on it in a test.

curl --request POST \
  --url "https://api.us.nylas.com/v3/templates/<TEMPLATE_ID>/render" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{ "variables": { "name": "Alex", "topic": "the proposal" } }'
Enter fullscreen mode Exit fullscreen mode

Previewing is the step that catches an unfilled placeholder or a misspelled variable name before a customer ever sees it, and it costs nothing to run. Because the render returns both the subject and the HTML body, you get exactly what the send would produce, which makes it safe to drop straight into a preview pane.

The CLI previews the same way with --render-only on a send. It renders the hosted template with your data and prints the result instead of delivering it:

nylas email send --to client@example.com --template-id <TEMPLATE_ID> \
  --template-data '{ "name": "Alex", "topic": "the proposal" }' --render-only
Enter fullscreen mode Exit fullscreen mode

Override a template per send

Sometimes a single send needs to differ from the template, a one-off subject line or a tweaked body for one recipient, without creating a whole new template. The send request handles this by letting the body and subject fields override the template's versions. If you pass a subject alongside a template, the send uses your subject instead of the template's, and the same goes for the body.

This keeps your template library from sprawling into near-duplicates. When most of a message matches an existing template and only the subject changes for one campaign, you reference the template for the shared body and override the subject inline, rather than cloning the template just to change one line. The template stays the canonical version, and the override is scoped to the single send that needs it.

Feed templates into workflows

Hosted templates pair with workflows, which send a templated message automatically when an event fires. An application-level workflow listens for a trigger, like a booking.created event, and sends a template you've defined to the relevant user, with no code running on your side at send time. The template supplies the copy and variables; the workflow supplies the trigger and the timing.

This is how you wire up transactional mail that should just happen on its own: a booking confirmation, a signup welcome, a status-change notice. You author the template once, attach it to a workflow that watches for the event, and Nylas sends it when the event occurs. The same template you'd use for a manual send becomes the payload of an automated one, so the copy stays consistent whether a person or a trigger sent it.

Manage your hosted templates

Templates accumulate, so the rest of the lifecycle is the usual CRUD against /v3/templates. A GET lists every template on your application, GET /v3/templates/{template_id} fetches one, PUT updates a template's name, subject, or body, and DELETE removes it. Updating is how a copy change propagates: edit the template once, and every future send that references it picks up the new wording, which is the entire point of pulling the copy out of your code.

curl --request GET \
  --url "https://api.us.nylas.com/v3/templates" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"
Enter fullscreen mode Exit fullscreen mode

Edit a template and the change is live for the next send that uses it, with no deploy on your side. That decoupling, copy in the template and logic in your app, is the reason to reach for hosted templates instead of inlining the string in three different send sites.

The CLI's templates are separate and local

Here's the part that surprises people. The CLI's nylas email templates commands do not manage the hosted templates above. They manage their own local templates, stored on your machine in ~/.config/nylas/templates.json, which are a terminal convenience and are not synced to the Nylas API. A template you create with nylas email templates create lives on your laptop, and a template you create with POST /v3/templates lives in the API; they're two separate stores that happen to share a name.

# This creates and uses a LOCAL CLI template, not an API-hosted one
nylas email templates create --name "Follow-up" --subject "Re: {{topic}}" \
  --body "Hi {{name}}, following up on {{topic}}." --category sales
nylas email templates use <local-template-id> --to client@example.com --var name=Alex
Enter fullscreen mode Exit fullscreen mode

So nylas email templates create, list, show, update, delete, and use all operate on those local files, and the CLI-only --category flag and --var substitution apply there. It's genuinely handy for firing a quick personalized send from the terminal, but don't expect templates use to send an API-hosted template by its API ID. When you want a hosted template from the terminal, that's nylas email send --template-id <id> with --template-data, shown earlier, which is the CLI surface for the API's hosted templates rather than this local store.

Things to keep in mind

A short list of practices keeps templated email maintainable.

  • Hosted and CLI templates are different stores. Hosted API templates live at /v3/templates (or /v3/grants/{grant_id}/templates); the CLI email templates group is local files in ~/.config. Don't cross the IDs.
  • strict is on by default. A missing variable fails the send loudly; set strict: false only when an empty value is acceptable.
  • Preview before sending. The render endpoint expands the subject and body so you catch typos and unfilled placeholders for free.
  • Write the body as HTML. Hosted template bodies are HTML, so use markup rather than plain text with newlines.
  • Override inline instead of cloning. Pass subject or body on the send to vary one message without spawning a near-duplicate template.

Wrapping up

Hosted templates move your email copy out of code and into a reusable resource with variables you fill at send time. Create one with POST /v3/templates, send from it by passing a template object with variables on a send, and preview with the render endpoint before anything reaches a recipient. Strict is on by default so a missing variable fails loudly, you can override subject or body for one-offs, and editing the template once changes the wording everywhere it's used. Just remember the CLI's email templates are a separate local store, not these hosted ones.

Where to go next:

Top comments (0)