Docs › API reference

API reference

Interactive reference. Browse and try every endpoint in the interactive API reference. It is generated directly from the API, so it is always in sync. The machine-readable OpenAPI 3 spec lives at mailhuset.com/openapi.json.

The page below is a hand-written overview. The Mailhuset REST API has base URL https://api.mailhuset.com/v1. All requests are authenticated with a Bearer API key and send/return JSON.

Authorization: Bearer $MAILHUSET_API_KEY
Content-Type: application/json

Send email

`POST /v1/email`: send a message. Full field list in Send email via the API.

POST /v1/email
{ "from": "Acme <hello@yourdomain.com>", "to": ["a@example.com"], "subject": "Hi", "html": "<p>Hello</p>" }

Messages (activity)

`GET /v1/email`: list recent messages with their status and events, for building your own activity view or reconciling sends.

Domains

Method	Path	Purpose
`POST`	`/v1/domains`	Add a sending domain
`GET`	`/v1/domains`	List domains and their status
`GET`	`/v1/domains/{domain}`	Get one domain + its DNS records
`POST`	`/v1/domains/{domain}/verify`	Re-check DNS and verify

See Verify a sending domain.

Webhook endpoints

Method	Path	Purpose
`POST`	`/v1/webhook-endpoints`	Register an endpoint
`GET`	`/v1/webhook-endpoints`	List endpoints

Event types are listed in Webhooks.

Conventions

Versioning: the path is versioned (/v1). New breaking shapes get a new version; additive fields don't.
Errors: standard HTTP status codes: 401 (auth), 403 (not permitted / domain not verified), 422 (validation, with the offending field), 429 (rate limited). Bodies include a message.
Idempotency: pass idempotencyKey on sends so retries don't double-send.

Import the spec

The OpenAPI document at mailhuset.com/openapi.json can be imported straight into your tools:

Postman / Insomnia: import by URL to get a ready-made request collection.
Client generation: feed it to openapi-generator to scaffold a client in your language.

openapi-generator-cli generate \
  -i https://mailhuset.com/openapi.json \
  -g typescript-fetch -o ./mailhuset-client

Libraries

Prefer a typed client? Use the Node & Python SDKs instead of raw HTTP.

Need help? Email support@mailhuset.com.