Documentation

Quickstart

Send your first email in a few minutes — over the HTTPS API or SMTP. You'll need a verified sending domain and an API key from the console.

1. Verify your sending domain

In the console, add your domain and publish the four DNS records shown (MX, SPF, DKIM, DMARC), then click Verify. Mailiya confirms SPF, DKIM and DMARC are live and aligned — this is what keeps your mail in the inbox. You can't send until your domain is verified.

Open the console →

2. Create an API key

Go to Settings → API keys and create a key. It's shown once — store it in your app's environment (for example MAILIYA_API_KEY). Keys are sent only in the Authorization header, never in a URL.

3. Send with the API

Make one authenticated POST to /v1/send with a JSON body. Provide text, html, or both.

curl https://api.mailiya.com/v1/send \
  -H "Authorization: Bearer $MAILIYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@yourdomain.com",
    "to": "customer@example.com",
    "subject": "Welcome aboard",
    "text": "Thanks for signing up!",
    "html": "<h1>Thanks for signing up!</h1>"
  }'

const res = await fetch("https://api.mailiya.com/v1/send", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.MAILIYA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    from: "hello@yourdomain.com",
    to: "customer@example.com",
    subject: "Welcome aboard",
    html: "<h1>You're in 🎉</h1>",
  }),
});
const data = await res.json(); // { id, status, ... }

A successful call returns a message id and a status:

{
  "id": "msg_2a9f…",
  "status": "queued"
}

4. Or send over SMTP

Prefer a mail library or an existing app? Generate an SMTP credential in Settings → SMTP and point your client at Mailiya. Authentication is required and only offered over TLS.

Host:      mail.mailiya.com
Port:      587   (STARTTLS)      or   465   (implicit TLS)
Username:  <your SMTP username>  (generate in Settings → SMTP)
Password:  <your SMTP password>  (shown once, on creation)
Auth:      required, over TLS only
From:      any address at your verified domain

5. Errors

Failed requests return a JSON error with a stable machine-readable code, so you can branch on the code rather than a message string:

{ "error": { "code": "domain_not_verified", "message": "…" } }

Next steps

• Watch delivery in the console's deliverability dashboard.
• Marketing sends include a one-click unsubscribe header automatically.
• New domains warm up automatically over ~30 days — send to engaged recipients first.