Documentation

Last updated: 15 October 2026

Everything you need to send your first email and track its results. Access is requested through the form.

1. Verify your domain

In the client portal, add your domain: zenoses generates one record to create at your DNS provider (yourdomain.com below). Exact values are shown in the portal.

TypeNameValue
CNAMEzenAAAAMM._domainkey.yourdomain.com<token>.dkim.zenoses.comRequired: a single record, which proves domain ownership and enables DKIM at once.
TXTyourdomain.comv=spf1 include:spf.zenoses.com ~allRecommended (SPF): if you already have an SPF, only add include:spf.zenoses.com to it. Not required to activate sending.
TXT_dmarc.yourdomain.comv=DMARC1; p=none; rua=mailto:dmarc@yourdomain.comRecommended
MXbounce.yourdomain.com10 mta1.zenoses.comRecommended (custom MAIL FROM)
TXTbounce.yourdomain.comv=spf1 include:spf.zenoses.com -allRecommended

If your DNS provider refuses a CNAME at that spot (some root-domain templates do), the client portal also shows the full TXT value as a fallback: it replaces the CNAME, don't publish both.

Then click “Verify”: sending is enabled as soon as ownership, DKIM and SPF pass. Only one SPF record is allowed per domain.

2. Get your key

Create a key in the client portal (“Keys” menu). It starts with zk_ and is shown only once: copy it immediately. You can revoke it at any time.

3. Sandbox (new accounts)

When opened, your account is in sandbox mode: you can only email test addresses you have verified (the "Sandbox" menu in the client portal; each address receives a confirmation link). Sending to an unverified address is refused (550). This mirrors AWS SES and protects sending reputation while you validate your integration. Ask for production access at contact@zenoses.com to email any address.

3. Send over SMTP

SettingValue
Hostsmtp.zenoses.com
Ports587 (STARTTLS) · 465 (implicit TLS)
AuthenticationPLAIN / LOGIN
Usernamezenoses (fixed value, like apikey on other services)
Passwordyour zk_… key

The From address must belong to a verified domain on your account.

cURL

curl --url 'smtp://smtp.zenoses.com:587' --ssl-reqd \
  --mail-from 'noreply@yourdomain.com' --mail-rcpt 'client@example.com' \
  --user 'zenoses:zk_your_key' -T message.eml

Python

import smtplib, ssl
from email.message import EmailMessage

m = EmailMessage()
m["From"] = "Your App "
m["To"] = "client@example.com"
m["Subject"] = "Hello"
m["X-Zenoses-Configuration-Set"] = "transactional"   # optional
m.set_content("Message text")

with smtplib.SMTP("smtp.zenoses.com", 587) as s:
    s.starttls(context=ssl.create_default_context())
    s.login("zenoses", "zk_your_key")
    s.send_message(m)

Node.js (nodemailer)

const nodemailer = require("nodemailer");
const t = nodemailer.createTransport({
  host: "smtp.zenoses.com", port: 587, secure: false, requireTLS: true,
  auth: { user: "zenoses", pass: "zk_your_key" },
});
await t.sendMail({ from: "noreply@yourdomain.com", to: "client@example.com", subject: "Hello", text: "Message text" });

4. Configuration sets

A configuration set groups your sending (for example “transactional” and “marketing”) to separate statistics and target webhooks. Add this header to your messages; it is stripped before delivery:

X-Zenoses-Configuration-Set: transactional

5. SMTP responses and errors

CodeMeaningWhat to do
250Message accepted (queued)—
535 / 530Invalid key / authentication requiredCheck the key (not revoked)
550 5.7.1Missing From, or domain not authorised for this accountVerify the domain in the portal
553 5.1.3Invalid recipient addressFix the address
554 5.7.1Sending paused (reputation), unknown or disabled configuration setContact support; do not retry in a loop
454 4.7.024-hour sending limit reachedRetry later or request an increase
450 4.7.1Maximum sending rate exceededSlow down and retry
451 4.3.xTemporary failureRetry with exponential back-off

4xx codes are temporary (retry); 5xx codes are permanent (do not retry without fixing).

6. Webhooks

Create a webhook in the client portal: an HTTPS URL (internal addresses are refused) and the events you want, optionally limited to one configuration set. Types: Send, Delivery, Bounce, Complaint, Reject, DeliveryDelay. Reply with a 2xx code within 8 seconds.

Sample notification

{
  "eventType": "Bounce",
  "id": "48213",
  "timestamp": "2026-10-15T12:31:07+00:00",
  "mail": { "messageId": "7f3a9c01b2e4", "destination": ["client@example.com"],
            "sendingDomain": "yourdomain.com", "configurationSet": "transactional", "tenantId": 12 },
  "bounce": { "bounceType": "Permanent",
              "bouncedRecipients": [{ "emailAddress": "client@example.com", "status": "5.1.1", "diagnosticCode": "550 5.1.1 user unknown" }] }
}

Headers

X-Zenoses-Signature: t=<timestamp>,v1=<hex> · X-Zenoses-Event-Type · X-Zenoses-Event-Id · X-Zenoses-Delivery-Id

Verify the signature

The signature is an HMAC-SHA256 of "<t>." + raw body using the webhook's whsec_… secret. Verify it on the raw body, before parsing JSON:

import hmac, hashlib, time

def verify(secret: str, header: str, body: bytes, tolerance=300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t, v1 = parts["t"], parts["v1"]
    if abs(time.time() - int(t)) > tolerance:      # replay
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)

Retries

On failure, zenoses retries after 1 min, 5 min, 30 min, 2 h and 6 h, then gives up on that delivery. A webhook failing 20 times in a row is disabled automatically (you are alerted).

7. Suppression list

Addresses that hard-bounce or complain are added automatically to your suppression list: later sends to them are skipped (if every recipient of a message is suppressed, it is accepted but nothing is sent). You can import, export and manage the list in the portal.

8. Limits and reputation

Your account starts with cautious limits (volume per 24 h and rate per second) that grow with the quality of your traffic. If bounces or complaints exceed the thresholds (bounces: warning at 5%, pause at 10%; complaints: warning at 0.1%, pause at 0.5%), the domain or account is paused automatically. See the acceptable use policy.

9. API HTTPS coming soon

An HTTPS sending API (with templates using {{name}} variables and bulk send) (authentication with your zk_… key as Authorization: Bearer) is being opened. Until then, use SMTP, which has the same limits and protections.