Everything you need to build on WiseSender

Overview

The base URL for every request is https://wisesender.com. Requests and responses are JSON, encoded as UTF-8. All endpoints allow cross-origin calls, but keep your keys on your server: a key in browser code can be copied by anyone.

Authentication

Create keys in the dashboard. Each key is shown once; only a hash is stored, so copy it somewhere safe. You can hold up to 10 keys of each type and revoke any of them instantly.

Verify one email

curl "https://wisesender.com/v1/[email protected]&mode=power" \
  -H "X-API-Key: ws_live_YOUR_KEY"

const url = 'https://wisesender.com/v1/verify?email=' + encodeURIComponent(email);
const res = await fetch(url, { headers: { 'X-API-Key': process.env.WISESENDER_KEY } });
const result = await res.json();

r = requests.get("https://wisesender.com/v1/verify",
                 params={"email": email, "mode": "quick"},
                 headers={"X-API-Key": KEY}, timeout=30)
result = r.json()

$ch = curl_init('https://wisesender.com/v1/verify?email=' . urlencode($email));
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['X-API-Key: ' . $key]]);
$result = json_decode(curl_exec($ch), true);

Verify in bulk

Send up to 1,000 addresses in one request. Duplicates are removed before charging. The request waits until every address is checked, so allow a long timeout in power mode; for bigger lists, upload a file in the dashboard instead.

curl https://wisesender.com/v1/verify/bulk \
  -H "X-API-Key: ws_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "emails": ["[email protected]", "[email protected]"], "mode": "power" }'

{
  "count": 2,
  "summary": { "safe": 1, "risky": 0, "invalid": 1 },
  "credits_refunded": 0,
  "results": [ { "email": "[email protected]", "status": "safe", ... }, ... ]
}

The result object

Categories

Lists and contacts

Add people to your contact lists from your own app, a CRM or an automation tool. Contacts added this way behave like a signup on your hosted form: lists with double opt-in email a confirmation first, and the list's welcome email goes out once they're subscribed.

Returns your lists with their IDs: { "lists": [{ "id": 12, "name": "Newsletter", "subscribed": 2140, "double_optin": true }] }

curl -X POST https://wisesender.com/v1/lists/12/contacts \
  -H "X-API-Key: ws_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]", "name": "Ann Lee", "verify": true }'

# 201 Created (200 if they were already on the list)
{ "email": "[email protected]", "status": "subscribed", "created": true }

status is subscribed, or pending when a confirmation email was sent.

Pages through a list. status can be subscribed, pending or unsubscribed; limit goes up to 1,000.

Unsubscribes the address and adds it to your do-not-send list, so no campaign or API send reaches it again.

Account events

Besides the delivery events below, your webhook URL receives events about your audience. Automation tools like Zapier, Make and n8n can start a workflow from them.

{
  "event": "contact.subscribed",
  "timestamp": "2026-11-11T09:14:03.120Z",
  "data": { "list_id": 12, "list": "Newsletter", "email": "[email protected]", "name": "Ann Lee", "source": "form" }
}

They're signed the same way as delivery events. See Webhooks.

Send an email

The from domain must be verified under Domains in the dashboard. Without cc or bcc, each to address receives its own copy and can carry its own merge_data. With cc or bcc, one message goes to everyone.

curl https://wisesender.com/v1/email/send \
  -H "Authorization: Bearer ws_send_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <[email protected]>",
    "to": [{ "email": "[email protected]", "name": "Jane", "merge_data": { "code": "482913" } }],
    "subject": "Your login code",
    "html": "<p>Hi {{name}}, your code is <b>{{code}}</b></p>",
    "tags": { "type": "otp" }
  }'

{
  "data": [
    { "id": "1842", "to": "[email protected]", "type": "to", "status": "sent" }
  ],
  "sandbox": false
}

Each recipient's status is sent, suppressed (on your do-not-send list), invalid (failed the optional check) or failed. Only sent uses an email credit.

Templates

Create templates in the dashboard and send them with template_key. Placeholders use double braces and support dotted paths:

Unknown placeholders become empty text. A recipient's own merge_data overrides the shared values, and name and email are filled from the recipient automatically.

Attachments

Pass a list of objects with a file name and base64 content. Up to 10 files and 10 MB in total. Executable file types are refused because mailbox providers block them.

"attachments": [
  { "name": "invoice-10482.pdf", "content": "JVBERi0xLjQK..." },
  { "name": "logo.png", "content": "iVBORw0KGgo...", "content_id": "logo" }
]
// reference the inline image in html as <img src="cid:logo">

SMTP relay

Use the relay when your software only speaks SMTP. The same domain checks, limits, logs and webhooks apply, and Bcc headers are removed before delivery.

Webhooks

Set an https URL in the dashboard under Transactional API, Webhooks. We POST one JSON event per recipient for sent, delivered, bounced, soft_bounced, complained, delayed, failed, opened and clicked.

{
  "event": "delivered",
  "message_id": "1842",
  "agent": "OTP",
  "from": "[email protected]",
  "to": "[email protected]",
  "recipient_type": "to",
  "subject": "Your login code",
  "tags": { "type": "otp" },
  "timestamp": "2026-11-10T09:14:03.120Z"
}

Check the signature

Every request carries X-WiseSender-Signature: sha256=<hex>, an HMAC-SHA256 of the raw body using your webhook secret. Compare it before trusting the event.

const crypto = require('node:crypto');
function isValid(rawBody, header, secret) {
  const good = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return header?.length === good.length && crypto.timingSafeEqual(Buffer.from(header), Buffer.from(good));
}

$raw = file_get_contents('php://input');
$good = 'sha256=' . hash_hmac('sha256', $raw, $secret);
if (!hash_equals($good, $_SERVER['HTTP_X_WISESENDER_SIGNATURE'] ?? '')) { http_response_code(401); exit; }

Errors

Errors return a non-2xx status and a body like { "error": "Invalid API key" }.

Limits

Need a higher limit? Ask support with your expected volume.