Documentation: send transactional email and receive replies

Overview

SimpleFlare treats sending and receiving as two halves of the same conversation. Your product calls one REST endpoint to send transactional email; the replies land in a unified inbox where your team answers them. Every business you run gets its own sender identity, templates, and inbox, all managed from one hub.

Send

One endpoint per project, authenticated with a rotating key. Template, wrapped HTML, or fully rendered HTML.

Receive

Inbound mail is threaded per project in a shared inbox with inline replies.

Deliver

Open, click, and bounce tracking, an automatic suppression list, and one-click unsubscribe.

Quickstart

Every request goes to a single endpoint:

POSThttps://simpleflare.app/api/email/send

Send your first email with a stored template and some data:

curl -X POST https://simpleflare.app/api/email/send \
  -H "X-Project-Key: sk_your_project_key" \
  -H "Content-Type: application/json" \
  -d '{
        "template": "welcome",
        "to": "[email protected]",
        "vars": { "name": "Ann" }
      }'
# => {"ok":true}

That is the whole loop: the API renders your project's welcome template with the data you passed and sends it from that project's support@ identity.

Authentication

Each project has its own Send API key, shown in the admin under the project's email templates. Pass it on every request in the X-Project-Key header. The key both authenticates the call and selects which project (identity, templates, design) the email is sent from.

Header	Value
`X-Project-Key`	Your project's secret key, e.g. `sk_live_...`. Rotate it any time from the admin; the old key stops working immediately.
`Content-Type`	`application/json`

Keep the key server-side. It can send email as your brand, so treat it like any other secret and never ship it in client-side code.

Send from a template

Reference a stored template by key and pass its data in vars. Four variables are injected automatically and never need to be passed: brand, app_url, login_url, and support_email.

curl -X POST https://simpleflare.app/api/email/send \
  -H "X-Project-Key: sk_your_project_key" \
  -H "Content-Type: application/json" \
  -d '{
        "template": "welcome",
        "to": "[email protected]",
        "vars": { "name": "Ann", "plan": "Studio" }
      }'

From Laravel:

Http::withHeaders(['X-Project-Key' => config('services.simpleflare.key')])
    ->post('https://simpleflare.app/api/email/send', [
        'template' => 'welcome',
        'to'       => $user->email,
        'vars'     => ['name' => $user->name],
    ]);

Dynamic HTML (loops, model data)

Most real emails (order confirmations, digests) are code: they loop over line items and translated strings that do not fit a string template. Render that content in your own app and pass it as content_html. SimpleFlare wraps it in the project's design shell and sends it from the project identity, so it still matches your brand.

curl -X POST https://simpleflare.app/api/email/send \
  -H "X-Project-Key: sk_your_project_key" -H "Content-Type: application/json" \
  -d '{
        "to": "[email protected]",
        "subject": "Order #1234 confirmed",
        "content_html": "<h1>Thanks!</h1><table>...your rows...</table>"
      }'

Rule of thumb: simple emails (welcome, notifications) use template; dynamic emails render in your app and use content_html. Either way, every email leaves with one unified design and identity.

Fully rendered HTML

If your project renders the complete email, including its own <html> shell, send it as html and SimpleFlare relays it as-is with no wrapping. Optional from, from_name, and text override the identity and add a plain-text part.

curl -X POST https://simpleflare.app/api/email/send \
  -H "X-Project-Key: sk_your_project_key" -H "Content-Type: application/json" \
  -d '{
        "to": "[email protected]",
        "subject": "Order #1234 confirmed",
        "html": "<!doctype html><html>...full email...</html>"
      }'

Recipients, CC and BCC

to is required; cc and bcc are optional. Each field accepts a single email string, an array of emails, or an array of {email, name} objects, and you can mix those freely. Invalid addresses are dropped, and each field is capped at 50 recipients.

curl -X POST https://simpleflare.app/api/email/send \
  -H "X-Project-Key: sk_your_project_key" -H "Content-Type: application/json" \
  -d '{
        "template": "notify",
        "to":  ["[email protected]", {"email": "[email protected]", "name": "Ben"}],
        "cc":  "[email protected]",
        "bcc": ["[email protected]"],
        "vars": { "name": "Team" }
      }'

Field	Required	Notes
`to`	Yes	String, array, or `{email,name}` objects. Max 50.
`template` / `content_html` / `html`	One of	How the body is produced. See the sending sections above.
`subject`	For HTML sends	Templates carry their own subject; HTML sends set it here.
`vars`	No	Data for template placeholders. Auto vars are added for you.
`cc`, `bcc`	No	Same shapes as `to`. Max 50 each.

Receiving replies

Every project has a support@<domain> address. Inbound mail is parsed and threaded into the unified inbox, grouped by project, where your team reads and replies inline. Replies go out wrapped in that project's design, so a conversation stays on-brand from the first send to the last answer.

Attachments on inbound mail are stored with a 25MB cap. Dangerous executable types are blocked for safety and shown as blocked rather than downloaded.

Templates

Templates are per-project and editable in the admin, with a live preview, test sends, and versioning. Each has a subject, an HTML body, and a plain-text fallback, and uses {{var}} placeholders. System templates such as welcome and notify fall back to built-in defaults until you save your own.

To carry over an existing email: open the project's templates, create a new key, paste your HTML, swap dynamic values for {{var}} placeholders, preview, and save. Your product then references it by key through the API.

Deliverability

Tracking: opens, clicks, and bounces are recorded per message.
Suppression: permanent (hard) bounces are added to a suppression list automatically, so you stop mailing addresses that will never deliver.
Unsubscribe: one-click List-Unsubscribe headers are supported.
A/B: template variants let you compare subject lines and content.

For the most critical transactional mail, such as magic links and password resets, keep a generally-available provider as a fallback until any beta transport you use reaches general availability.

Responses and errors

A successful send returns 200 with {"ok":true}. Errors return a matching status code and an error message.

Status	Meaning
`200`	Sent. Body is `{"ok":true}`.
`401`	Missing or invalid `X-Project-Key`.
`402`	Trial ended. Pick a plan to resume sending.
`422`	Validation failed, for example no valid recipient or a body that could not render.

Ready to build? Start a free 14-day trial, add your first business, and send a test in minutes.