POST/emails/send-template

POST /emails/send-template

Send an email using a template with dynamic variables.

Request

curl -X POST 'https://api.sendheron.com/api/v1/emails/send-template' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json'

Required scopes

The key must carry these:

emails:send

Body parameters

Name	Type	Required	Description
to	string	Yes	Recipient address.
templateId	uuid	Yes	Template to render.
variables	object	No	Values for the template's Handlebars variables. Merged with the auto-populated `contact.*` set when `contactId` is given.
contactId	uuid	No	Fills in `contact.firstName`, `contact.lastName`, `contact.email` and the contact's properties, and guarantees the unsubscribe headers. Send it whenever the recipient is a known contact.
subject	string	No	Overrides the template's subject. Takes the same variables.
from	string	No	Defaults to the workspace's configured sender.
fromName	string	No	Display name for this send, shown beside the address and overriding the sender identity's. The address is what domain verification gates, so the name may vary per send: one verified address, several product names. At most 100 characters, with no line breaks and no angle brackets.
replyTo	string	No	Reply-To address.
cc	string[]	No	Up to 50 addresses. Each is checked against the suppression list on its own, because a cc is a real delivery, and a blocked copy is dropped without failing the message.
bcc	string[]	No	Up to 50 addresses, suppression-checked the same way, and a blocked copy is likewise dropped rather than failing the message.
sendAt	ISO-8601 datetime	No	Schedule the send instead of dispatching it now. Must be in the future. The template REFERENCE and the variables are stored, and rendering, the contact merge, and every compliance and plan gate run when it fires, so the recipient gets the template as it exists then. Cancel before it fires with `DELETE /emails/scheduled/{id}`. Cannot be combined with `attachments`.
attachments	object[]	No	At most 10 per message and 10 MB of decoded bytes across all of them together, in the same shape SendGrid takes. Only allowed when the template is `TRANSACTIONAL`. Cannot be combined with `sendAt`. The nested fields are documented below.
attachments[].content	string	Yes	File content, base64-encoded. The bytes are passed straight to the provider and never stored, and they are deliberately excluded from the idempotency-key payload comparison: a retried job that regenerated the same file (a fresh creation timestamp inside the PDF) replays the original response instead of failing the key with a 409. `filename` and `type` still count towards that comparison.
attachments[].filename	string	Yes	Filename shown to the recipient, e.g. `receipt-1234.pdf`.
attachments[].type	string	Yes	MIME type, from the allowlist: `application/pdf`, `image/png`, `image/jpeg`, `image/gif`, `image/webp`, `text/calendar`, `text/csv`, `text/plain`, `application/zip`. Anything else is refused.
attachments[].disposition	string	No	Only `attachment` is accepted. The field exists for SendGrid payload compatibility; inline (CID) images are not supported.

This route follows the template's emailType, so it is the one to reach for when you want a transactional template treated as transactional. Set the type on the template, not on the send. A 201 is an outcome, not proof of dispatch: status is sent or suppressed, with the machine-readable reason in errorMessage, per Send outcomes. With sendAt, the body is the scheduled email rather than a send record. The template engine is Handlebars, and the built-in helpers all work: {{#if}}, {{else}}, {{#each}} (nesting included), {{this}}, {{@index}}, {{#unless}}, {{#with}} and {{lookup}}. Five Liquid-style pipe filters are converted automatically, so {{ name | upcase }} works: prepend, append, default, upcase and downcase. {{var}} HTML-escapes its value and {{{var}}} is the raw form. A variable that is referenced but missing renders as an empty string, and a template that fails to compile fails the send, and the preview, with a 400 templates.renderFailed.

Responses

Returns 201 on success.

400: The payload failed validation, or the request is not valid for the current state. The body's `description` names the field and says what was wrong with it in words, e.g. "domain: domain must be a bare hostname such as acme.com, with no scheme, path, or port". The `error` code is stable and safe to branch on; `description` is for the human reading the log.
401: Missing or invalid API key.
403: Valid key, but it does not carry the required scope. The `error` code is `apiKeys.insufficientScopes` and the `description` names both halves of the problem: "Missing required scope(s): X. This key holds: Y." Neither is a secret, since the required scopes are on this page and the held ones are your own credential, and a bare "Forbidden" costs a debugging pass to work out which of the two it was.
404: No such record in this workspace. An id belonging to a different workspace returns this too, never a 403, because the API will not confirm that a record exists outside the workspace your key was issued in. Read it as "not yours or not there" rather than as "definitely gone".
409: A duplicate, or an idempotency key reused with a different payload.
429: Either rate-limit ceiling was exceeded.
400: emailSending.marketingRequiresContact: the template is marketing-typed and `to` is not a contact in the workspace. The one-click unsubscribe token is minted from a contact record, and marketing without a working unsubscribe is refused rather than shipped. Create the contact first, or pass `contactId`.
400: `emailSending.attachmentsRequireTransactional`: the template is marketing-typed and the request carries attachments. Marketing mail does not get MIME attachments, because attachments on bulk mail are a deliverability red flag.
400: `templates.renderFailed`: the template failed to compile, so the send is refused rather than mailing its raw `{{...}}` source.
400: `emailSending.tooManyAttachments`, `emailSending.attachmentsTooLarge` or `emailSending.attachmentTypeNotAllowed`: an attachment cap or the MIME allowlist was breached. The keys are stable, so branch on them rather than on the text.
400: `emailSending.attachmentsNotSchedulable`: `attachments` and `sendAt` in the same request. Attachment bytes are never stored, so a scheduled send would have nothing left to attach when it fires.
403: subscription.sendPoolExhausted: the template is marketing-typed and the pooled monthly send allowance is spent. The pool resets with the calendar month; a higher tier raises it.
403: subscription.transactionalGraceExhausted: the template is transactional-typed and the pool plus the 10% transactional fair-use grace is spent.
403: subscription.lapsed: a marketing-typed send with no active subscription. Transactional-typed sends are not refused for lapsing; they run within the smallest plan's grace.
503: `emailSending.sendFailed`: the provider refused the send. The FAILED attempt is recorded and the idempotency key is released, so retry with the SAME key.

Rate limits

100/min per key, counted against the organization's SEND ceiling (200/min). Both windows are one minute. There is no hourly or daily quota.