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.
| Type | Name | Value | |
|---|---|---|---|
| CNAME | zenAAAAMM._domainkey.yourdomain.com | <token>.dkim.zenoses.com | Required: a single record, which proves domain ownership and enables DKIM at once. |
| TXT | yourdomain.com | v=spf1 include:spf.zenoses.com ~all | Recommended (SPF): if you already have an SPF, only add include:spf.zenoses.com to it. Not required to activate sending. |
| TXT | _dmarc.yourdomain.com | v=DMARC1; p=none; rua=mailto:dmarc@yourdomain.com | Recommended |
| MX | bounce.yourdomain.com | 10 mta1.zenoses.com | Recommended (custom MAIL FROM) |
| TXT | bounce.yourdomain.com | v=spf1 include:spf.zenoses.com -all | Recommended |
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
| Setting | Value |
|---|---|
| Host | smtp.zenoses.com |
| Ports | 587 (STARTTLS) · 465 (implicit TLS) |
| Authentication | PLAIN / LOGIN |
| Username | zenoses (fixed value, like apikey on other services) |
| Password | your 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
| Code | Meaning | What to do |
|---|---|---|
| 250 | Message accepted (queued) | — |
| 535 / 530 | Invalid key / authentication required | Check the key (not revoked) |
| 550 5.7.1 | Missing From, or domain not authorised for this account | Verify the domain in the portal |
| 553 5.1.3 | Invalid recipient address | Fix the address |
| 554 5.7.1 | Sending paused (reputation), unknown or disabled configuration set | Contact support; do not retry in a loop |
| 454 4.7.0 | 24-hour sending limit reached | Retry later or request an increase |
| 450 4.7.1 | Maximum sending rate exceeded | Slow down and retry |
| 451 4.3.x | Temporary failure | Retry 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.