Documentation

Send with templates

Save an email once, then personalize it each time you send.

A template contains a reusable subject and email body. Add placeholders for values such as a name or product, then supply those values when your application sends the email. Use the same send method as a regular message.

1. Create and publish a template

Open your dashboard, choose your sending domain and open Templates. Create a template, save it and publish a version. A saved draft cannot be sent through the API.

Use simple placeholders such as {{name}} and {{product}} in the subject or body. For example, a subject could be Welcome to {{product}}, {{name}}. Copy the template’s ID or slug; the examples below assume you published a template with the slug welcome.

The template must belong to the same domain as your sending API key. Your sender address must also belong to that verified domain. Keep the API key on your server, not in browser code.

2. Send with your values

Replace the example addresses with your verified sender and a controlled recipient. Supply a value for every placeholder used by the template.

Send with your values
Provider

Uses published SendHog templates, not templates or IDs owned by another provider.

import { SendHog } from '@sendhog/sdk';

const client = new SendHog({ apiKey: process.env.SENDHOG_API_KEY ?? '' });

const message = await client.send({
  "from": "hello@example.com",
  "to": "alex@example.net",
  "template": {
    "id": "welcome",
    "variables": {
      "name": "Alex",
      "product": "Example"
    }
  }
});
console.log(message.id);
Install SDKnpm install @sendhog/sdk

Install the libraries using the SDK guide. Native SendHog and SendHog’s Resend-style clients support published SendHog templates. Template IDs from other providers are not interchangeable.

Choose a version

Without version, SendHog uses the latest published version. To keep a production workflow on a specific version, add a positive version number inside template, for example { id: "welcome", version: 2, variables: { name: "Alex", product: "Example" } }. That version must already be published.

Published versions are snapshots: editing a draft does not change an earlier version. You may provide subject on the send request to override the saved subject. Do not combine template with inline html or text.

Variable rules and errors

  • Use up to 50 variables. Names start with a letter and contain only letters, numbers and underscores, up to 50 characters.
  • Values can be strings, numbers or booleans; strings can contain up to 2,000 characters. Objects, arrays, expressions and raw HTML placeholders are not supported.
  • HTML text values are escaped. Variables in attributes are limited to links, image sources, alternative text and titles; unsafe URLs are rejected.
  • Missing values or unsafe substitutions fail before sending. The rendered subject is limited to 1,000 characters on one line; each rendered body is limited to 100,000 characters.

TemplateNotFound means the ID, slug or published version is unavailable in the key’s domain. InvalidTemplateVariables means a value is missing, unsafe or outside the rendering limits. Fix the request rather than retrying unchanged.

When does the call return?

send waits for Amazon SES to accept or reject the email. Success returns { id, created_at } after acceptance is saved. It does not wait for delivery to the recipient’s mail server. See webhooks and events for the difference.

Template sends use the same account allowances, sending limits, suppressions and abuse protections as other sends. A provider timeout can leave the outcome unknown; do not blindly send again.

Send personalized email to multiple people

Use sendBulk in JavaScript/TypeScript or send_bulk in Python with SDK version0.2.0 or newer; see the installation guide for upgrading or installing an exact source tag. This sends a separate email to each of1–50 distinct recipients. Shared template variables form the defaults; each recipient’s variables override them. The whole request uses one published template version.

Send personalized bulk email
Provider

Personalized bulk uses the native SendHog SDK and requires version 0.2.0 or newer.

import { SendHog } from '@sendhog/sdk';

const client = new SendHog({ apiKey: process.env.SENDHOG_API_KEY ?? '' });

const result = await client.sendBulk({
  "from": "hello@example.com",
  "template": {
    "id": "welcome",
    "variables": {
      "product": "Example"
    }
  },
  "recipients": [
    {
      "to": "alex@example.net",
      "variables": {
        "name": "Alex"
      }
    },
    {
      "to": "sam@example.net",
      "variables": {
        "name": "Sam"
      }
    }
  ]
}, { idempotencyKey: 'welcome-batch-001' });

for (const recipient of result.results) {
  console.log(recipient.to, recipient.status, recipient.id);
}
Install SDKnpm install 'git+https://github.com/SendHog/sdk-node.git#v0.3.0'

For HTTP, POST the same JSON fields to /v1/send/bulk with an Idempotency-Key header. The key is required. Keep it stable when repeating the same request; changed content with the same key is rejected.

An array of addresses in a regular send’s to sends one shared message with the same values; it is not personalized bulk sending, and recipients may see the other To addresses.

Understand individual results

  • accepted: SES accepted this recipient’s separate email.
  • rejected: the provider explicitly refused the attempt.
  • unknown: dispatch may have happened; do not send again blindly.
  • not_sent: this item was not dispatched, for example because of suppression, a limit or the request deadline.

Bulk sends are synchronous and paced to the shared sending rate. The SDK allows up to120seconds for the request; the API stops starting new attempts after80seconds and reports the remainder as not_sent. Up to2,000 new bulk operations per domain per rolling24hours are allowed; normal recipient allowances still apply. No automatic continuation or email queue exists. A bulk request can partially succeed.

Inspect an existing operation with sendhog.bulk.get(result.id) or GET /v1/send/bulk/{id}. While processing, results are a snapshot: not_sent may simply mean not attempted yet. Wait for the original request to finish before deciding whether to create another operation. A repeated idempotent request never resumes or resends previous items.

An explicit customer queue option is deferred. Do not pass queue to sending methods or recipients to the single-message send method; unsupported fields produce an error.