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 }`.
`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" }
}

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.