Quickstart

1. Create an account and verify your email

Registration happens in the dashboard at zsender.io/register: it's protected by a CAPTCHA challenge, so it can't be scripted with curl. After you register, zSender emails you a verification link.

Click it before doing anything else. An unverified account can log in, but it cannot add a domain, create an API key, or send a live email: three separate gates, all keyed off the same check: has anyone on this account verified an inbox. Test mode (see step 4) is the one exception, since nothing it sends is ever delivered.

2. Create an API key

Create your first key from the dashboard's API Keys page (Create key). The plaintext key is shown exactly once, at creation. Copy it now. zSender stores only a hash, so a lost key can't be recovered; revoke it and create a new one instead.

Give it the admin permission: the rest of this guide adds a domain, which requires it. See Authentication for what each permission gates; once your domain is verified, consider creating a narrower send+read key for your application and keeping this one aside.

Once you hold one key with admin, you can mint further keys programmatically instead of going back to the dashboard:

curl -X POST https://api.zsender.io/api/tenants/YOUR_TENANT_ID/api-keys \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-backend",
    "permissions": ["send", "read"]
  }'

Set API_KEY to the key from the dashboard step for the rest of this guide.

3. Add and verify a sending domain

You can only send from a domain you've verified. Register one:

curl -X POST https://api.zsender.io/v1/domains \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "example.com"}'

The response's dns_records array holds five records for a sending-only domain: an SPF TXT, a DKIM TXT, and a return-path CNAME: those three are what capabilities.sending.status actually gates, plus a tracking CNAME and a DMARC TXT, which are reported for visibility but never block verification. Publish at least the first three at your DNS provider, then ask zSender to check them:

curl -X POST https://api.zsender.io/v1/domains/DOMAIN_ID/verify \
  -H "Authorization: Bearer $API_KEY"

DNS propagation can take a few minutes. Re-run the verify call until capabilities.sending.status reads VERIFIED.

4. Send an email

curl -X POST https://api.zsender.io/v1/emails/send \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["recipient@example.com"],
    "from": "hello@example.com",
    "subject": "Hello from zSender",
    "text": "This is a test email sent through zSender."
  }'

import { Zsender } from 'zsender-sdk';

const zsender = new Zsender(process.env.ZSENDER_API_KEY!);

const sent = await zsender.emails.send({
  to: ['recipient@example.com'],
  from: 'hello@yourverifieddomain.com',
  subject: 'Hello from zSender',
  text: 'Your first email through the API.',
});

console.log(sent.messageId);

from must be an address on the domain you just verified: bare, or with a display name in front of it in angle brackets (Acme <hello@example.com>). A successful send answers with the message's id. Use it to look up delivery events later at GET /v1/emails/:id/events.

Try it without sending real mail

The dashboard's API Keys page can also generate a test-mode key: prefixed zst_ instead of zs_. Swap it in for $API_KEY above and the same request runs through the real pipeline (DKIM signing, tracking-link rewrite, everything) but is captured in your sandbox inbox instead of delivered, and it skips domain verification entirely, so you can send from any address while you're still setting up DNS.