Send API

Prerequisites

Two things must exist on your account before the API will send. Both are set up once in the customer portal.

1. A verified sending domain

You may only send from an address whose domain you have verified — that means publishing the ownership TXT record, SPF include:_spf.malumail.com, and the DKIM record we generate for you. Sending from an unverified domain returns 403.

DKIM signing and SPF alignment are then automatic. You never sign anything yourself.

2. An API key

Portal → API Keys → create one. The key is shown once and cannot be recovered, so store it somewhere safe.

• Format: mm_ followed by 48 lowercase hex characters (51 characters total). The server enforces ^mm_[a-f0-9]{48}$.
• Each key is bound to a dedicated relay credential behind the scenes — you never handle SMTP directly when using the API.
• Revoking a key in the portal disables it immediately (401 thereafter).

Authentication

Send your key as a Bearer token on every request:

Authorization: Bearer mm_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f

Failure modes

Both return 401:

Send an email

Request body

The server generates Date, Message-ID (<token@your-domain>), and MIME-Version automatically.

Response

Success — 200 OK

{
  "status": "sent",
  "accepted": ["alice@example.com"],
  "rejected": [
    {"email": "bob@example.com", "reason": "suppressed:bounce"},
    {"email": "not-an-email",    "reason": "invalid_address"}
  ]
}

• accepted — recipients the message was relayed for (deduplicated, lowercased).
• rejected — recipients dropped before sending, each with a reason:
  • invalid_address — not a valid email.
  • suppressed:<reason> — on your suppression list or the global list (e.g. suppressed:bounce, suppressed:manual). These are never delivered.

Examples

curl -sS -X POST https://api.malumail.com/v1/send \
  -H "Authorization: Bearer $MALUMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "noreply@yourdomain.com",
    "from_name": "Your App",
    "to": ["alice@example.com", "carol@example.com"],
    "subject": "Welcome aboard",
    "text": "Thanks for signing up.",
    "html": "<p>Thanks for signing up.</p>"
  }'

import os, requests

resp = requests.post(
    "https://api.malumail.com/v1/send",
    headers={"Authorization": f"Bearer {os.environ['MALUMAIL_API_KEY']}"},
    json={
        "from": "noreply@yourdomain.com",
        "from_name": "Your App",
        "to": "alice@example.com",
        "subject": "Welcome aboard",
        "html": "<p>Thanks for signing up.</p>",
    },
    timeout=30,
)
resp.raise_for_status()          # raises on 4xx/5xx
data = resp.json()
if data["rejected"]:
    ...                          # some recipients were suppressed/invalid

const res = await fetch("https://api.malumail.com/v1/send", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MALUMAIL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    from: "noreply@yourdomain.com",
    to: "alice@example.com",
    subject: "Welcome aboard",
    html: "<p>Thanks for signing up.</p>",
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);

Suppression management

Suppressed addresses are silently refused by /v1/send — they come back in rejected. Bounces and spam complaints are added to your list automatically by the platform; these endpoints let you read and manage it.

List suppressions

{
  "suppressions": [
    {
      "email": "bob@example.com",
      "reason": "bounce",
      "created_at": "2026-07-30T01:00:00Z",
      "is_global": false
    }
  ]
}

• Returns your entries plus any global platform suppressions (is_global: true).
• Optional ?search= does a case-insensitive substring match on the address.
• Capped at 1000 rows, newest first.

Add a suppression

{"email": "user@example.com", "reason": "unsubscribe"}

• reason must be "manual" or "unsubscribe" (defaults to manual).
• 201 → {"status":"suppressed","email":...,"reason":...}
• 409 if the address is already suppressed.

Delete a suppression

• Removes your suppression for that address. 200 → {"status":"deleted","email":...}
• 404 if there is no entry for that address on your account.
• Global suppressions cannot be removed via the API.

Status codes

Error bodies are always {"error": "<message>"} — except the all-rejected 400, which also includes rejected.

Behavior to design around

• Sender authorization is enforced server-side. A verified from domain is mandatory; there is no way to spoof another domain.
• Suppression is enforced server-side. You cannot send to a suppressed address even if you try — it lands in rejected. Respect it in your own logic to avoid wasted calls.
• Rate limits come from your account plan (max_per_hour / max_per_day). Each accepted recipient counts as one unit — a send to 10 recipients uses 10 units. Over the limit returns 429 and the message is not sent.
• Deduplication: duplicate addresses in to collapse to one.
• Authentication (SPF/DKIM/DMARC) is handled by the platform for verified domains — you don't sign or add auth headers.

Limitations

This is a lean send API. It does not currently support:

• Attachments or inline images (bodies are text / html only).
• cc, bcc, Reply-To, or arbitrary custom headers.
• Templates, merge variables, or per-recipient personalization — each request sends one message.
• Scheduled or delayed sends.
• Open/click tracking, a List-Unsubscribe header, or delivery webhooks.

Integration checklist

1. Verify your sending domain in the portal; confirm it shows Verified.
2. Create an API key and store it as a secret (env var or secrets manager). Never commit it.
3. Send from an address on the verified domain.
4. On 200, inspect rejected — treat suppressed:* as permanent (don't retry those recipients) and invalid_address as a data-quality issue.
5. Retry only 429, 502, and transient 5xx, with exponential backoff. There is no idempotency key, so never blindly retry a request that already returned 200 — you would double-send.
6. Feed your own unsubscribe and complaint signals into POST /v1/suppressions.
7. Warm up gradually on a new domain or account before high volume.