Docs › Send email via the API

Send email via the API

Send with a single POST to /v1/email, authenticated with a Bearer API key. The from address must be on a verified domain.

Request

POST https://api.mailhuset.com/v1/email
Authorization: Bearer $MAILHUSET_API_KEY
Content-Type: application/json

{
  "from": "Acme <hello@yourdomain.com>",
  "to": ["customer@example.com"],
  "subject": "Your receipt",
  "html": "<p>Thanks for your order.</p>",
  "text": "Thanks for your order."
}

Fields

Field	Type	Notes
`from`	string	`Name <address>`; address must be on a verified domain. Required.
`to`	string[]	One or more recipients. Required.
`cc`, `bcc`, `replyTo`	string[]	Optional.
`subject`	string	Required unless a template supplies it.
`html`, `text`	string	The body. Send both when you can (better deliverability).
`templateAlias`, `templateModel`	string, object	Render a stored template with a data model; `subject`/`html`/`text` override the rendered output.
`stream`	string	`transactional` (default) or `broadcast`.
`headers`	object	Custom headers.
`tags`	object	Key/value tags for filtering in Activity.
`tracking`	object	`{ "opens": true, "clicks": true }`. Unset fields follow the stream (see below).
`idempotencyKey`	string	A repeat with the same key returns the original message instead of sending twice.

Response

A 2xx returns the accepted message (with its id). The message is then queued and delivered; track its state in Activity or via webhooks.

Templates

Store reusable content and send it by alias:

{
  "from": "Acme <hello@yourdomain.com>",
  "to": ["customer@example.com"],
  "templateAlias": "welcome",
  "templateModel": { "name": "Sam", "plan": "Pro" }
}

Open and click tracking

Broadcasts track opens and clicks by default. Transactional mail does not, unless you ask for it per message with tracking. Either default can be overridden, for example { "opens": false, "clicks": false } on a broadcast.

Opens add a small invisible image to the HTML. Treat them as a rough guide: Apple Mail loads images for its users whether they read the message or not, and plain-text mail has nothing to load.
Clicks send each link through a tracking redirect first. Leave them off for password resets and one-time links, since link scanners in corporate mail follow links before the recipient does.

Tracked messages raise email.opened and email.clicked webhooks and show in Activity.

Idempotency

Network retries can double-send. Pass a unique idempotencyKey per logical email and Mailhuset returns the original result on a repeat, safe to retry.

Errors

401 = bad/missing key; 403 = from domain not verified or sending not approved; 422 = validation error (the response says which field). See Troubleshooting.

Need help? Email support@mailhuset.com.