Skip to main content
POST

Overview

Use this endpoint when you want to send a transactional email without creating a template in the dashboard. You provide the rendered HTML yourself and Minimo handles dispatch, delivery, and tracking. Typical use cases:
  • Server-side rendered receipts: invoices, order confirmations, shipping notifications
  • Authentication flows: magic links, OTP delivery, email verification
  • Internal notifications: alerts produced by your own background jobs
  • Anything dynamic enough to not fit a pre-defined template
Tracking (open pixel + click rewriting) is injected server-side. Send your raw HTML as-is: don’t pre-rewrite links or append a pixel yourself. Click rewriting follows your Settings → Tracking → Email switch (on by default).

Before You Start

  1. Create an API key with the Transactional permission in Developer → API keys.
  2. Nothing else to set up: Minimo sends the email. Until you verify a sending domain, it goes out from a shared Minimo address with your workspace’s name; to send from your own domain see Senders and domains.
  3. Have your HTML body ready. Minimo does not render templates for this endpoint.

Sending for one of your customers

If your app sends email for its own customers (for example restaurants), add tenant with your id for that customer. Once your widget settings are saved, the recipient becomes that customer’s guest, and the email counts in that customer’s history and statistics and in GET /public/v1/messages/list?tenant=…. Minimo does not check marketing consent on this endpoint: use it for service emails (confirmations, reminders). See Start here for the other ways to send. To send guests’ replies to your customer, add replyTo, for example "replyTo": "Trattoria da Mario <trattoriadamario@gmail.com>". Any mailbox works, also one outside your verified domains. To show the customer’s name as the sender, add fromName, for example "fromName": "Trattoria da Mario". It works before you verify a domain too. Without it, guests see your workspace’s name.

What the Server Does to Your HTML

When you send html, the backend:
  1. Resolves placeholders: {{UNSUBSCRIBE_URL}}, {{PREFERENCES_URL}}, and {{FAKE_IMAGE_URL}} are replaced with the per-recipient tracked URLs.
  2. Strips any pre-existing tracking pixel: an <img> whose src matches the Minimo open-pixel pattern is removed so it can’t double-fire.
  3. Rewrites tracked anchors: every <a href> pointing to http(s) or a relative URL is replaced with a click-tracking URL. mailto:, fragment-only (#…), and pre-existing /api/click/* links are left alone. This step runs only while click tracking is on in Settings → Tracking → Email (the default); when you turn it off, links go out exactly as you wrote them, while the placeholders above and the open pixel still apply.
  4. Appends the open-tracking pixel at the end of <body> (or at the document root if no <body> exists).
The recipient receives the final HTML; analytics flow into GET /public/v1/emails/{id}/stats.

Example Request

Response Shape

A request that passes validation answers HTTP 201, also when the provider then rejects the message: read status (sent or failed) to know what happened.
When the provider rejects the message you still get back the same id, so the delivery row remains queryable:

Use Cases

Plain HTML with a single CTA is enough: the open and click events surface in the stats endpoint.

Best Practices

Pair every send with a statsUrl lookup

The response includes statsUrl. Persist the id (or the full statsUrl) alongside whatever business object triggered the send (order id, user id, etc.) so you can correlate opens and clicks later.

Handle the failed branch

status: "failed" means the provider rejected the message, usually a malformed recipient, an unverified sender, or a hard bounce. Surface failureReason to your operators, then either retry with corrected data or log the failure.

Keep HTML self-contained

Inline your CSS. Many email clients drop <style> blocks. Test in major clients (Gmail, Apple Mail, Outlook) before going live.

Provide a text fallback for deliverability

Spam filters reward multipart messages. Adding a plain-text alternative reduces the chance of landing in the junk folder.

Don’t double-track

If your HTML already contains /api/click/* URLs or an open pixel from a previous Minimo send, leave them alone: the server detects and skips them. Inserting your own tracking on top is unnecessary.

Common Errors

Errors use the standard error body { "status": "FAIL", "message": "<CODE>", "userMessage": "…" }.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
to
string<email>
required

Recipient email address.

subject
string
required

Email subject line.

html
string
required

Pre-rendered HTML body. The server injects the open pixel and rewrites anchor hrefs — do not pre-process them on your side.

text
string

Plain-text fallback for clients without HTML support.

fromAddress
string<email>

Sender address for this send. Must be under a VERIFIED sending domain of your workspace, otherwise 422 (never a silent fallback). Omit every sender field to use the workspace default. At most one of senderId, from, fromAddress.

from
string

Same as fromAddress, also accepting "Name <address@domain>".

Example:

"Trattoria Da Mario <prenotazioni@trattoriadamario.it>"

senderId
integer

Id of a sender from GET /public/v1/domains/{id}/senders. Its domain must be verified, otherwise 422.

Example:

34

fromName
string

Per-request sender display name override.

tenant
string

Your own reference for the customer this send belongs to. Stored on the message; filter with GET /public/v1/messages/list?tenant=.

Maximum string length: 64
Pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]*$
Example:

"restaurant-4812"

replyTo
string

Where replies go. "Name

" or a bare address. Any mailbox works, also one outside your verified domains (for example the restaurant's own Gmail). Omit it to keep your workspace default. A malformed value answers 422 INVALID_REPLY_TO and nothing is sent.

Maximum string length: 320
Example:

"Trattoria da Mario <trattoriadamario@gmail.com>"

Response

Delivery accepted by the queue. Check data.status to tell whether the provider actually accepted the message.

data
object