Sign in

v1

latestOpenAPI 3.1.02026-07-1315527.8 KB
Public API

Send transactional email

Send a transactional email via the public API. Automatically creates or updates the recipient contact.

Required content: either a template ID, or both subject and body. Template fields can be overridden by explicit request fields.

Sender: from is required unless using a template that already has a from configured. The sender's domain must be verified.

Multiple recipients: when to is an array, each recipient is processed sequentially with its own contact upsert and rendered email — there is no batch-send semantics. Sending is always immediate; for scheduled sends, use a Campaign.

Attachments: up to 10 attachments per email and 10 MB total by default. The total message size cannot exceed 40 MB.

post/v1/send

Headers

Idempotency-Keystring

Optional key that guarantees this request runs at most once. If the key was already used by your project, the request is refused with 409 instead of being performed a second time. Keys are scoped to your project, expire after 24 hours (configurable when self-hosting), and must be 1-255 printable ASCII characters.

Request body

subjectstring

Email subject. Required if no template is provided. Cannot contain newline characters.

bodystring

Email body (HTML). Required if no template is provided.

templatestring

Template ID to use for this email. When provided, uses the template's subject, body, from, and reply-to settings. You can override these by explicitly providing subject, body, from, or reply fields in the request. Template variables are populated from the data field.

namestring

Deprecated. Sender display name. Prefer from: { name, email }. Used only as a fallback when from is a string and no name is set there.

subscribedboolean

Subscription state to apply to the recipient. For new contacts, defaults to false on /v1/send. For existing contacts, omitting this preserves their current state — pass true or false to explicitly change it. A change emits contact.subscribed or contact.unsubscribed.

dataobject

Variables for template rendering and contact data updates. Each value can be:

  • A primitive (string, number, boolean) — saved on the contact and available as a template variable.
  • null — deletes the field from the contact.
  • An empty string — skipped (does not overwrite existing data).
  • An object { value, persistent: false } — used for this send only, not stored on the contact (good for one-shot password reset codes, magic links).

Reserved keys (id, plunk_id, plunk_email, email, unsubscribeUrl, subscribeUrl, manageUrl) are silently filtered out.

headersobject

Custom email headers. Header names cannot contain \r\n. Header values are limited to 998 characters and cannot contain \r\n (header injection is rejected).

replystring email

Reply-to address.

Response

Email queued successfully

successboolean
All 15 operations