Common Recipes
Production-grade patterns that save you reinventing the wheel.
The send samples use the Node.js SDK with
this setup. Bodies use the API's snake_case field names:
import { Configuration, PartnerEmailSendApi } from "@splashifypro/sdk";
const send = new PartnerEmailSendApi(
new Configuration({
basePath: "https://api.splashifypro.com/api/v1",
apiKey: `Bearer ${process.env.SPLASHIFY_API_KEY}`,
}),
);Idempotent transactional sends
Replays of the same logical send (e.g. payment-receipt for the same
charge ID) shouldn't trigger duplicate emails. We don't currently
honor an idempotency header (roadmap), so de-dup on your side against
your business key before calling /send:
async function sendReceipt(chargeId, customerEmail, receiptHtml) {
const sentKey = await redis.get(`email:sent:${chargeId}`);
if (sentKey) return; // already emailed
const res = await send.partnerEmailSendPost({
body: {
from: "[email protected]",
to: [customerEmail],
subject: "Your payment receipt",
html_body: receiptHtml,
},
});
await redis.set(`email:sent:${chargeId}`, res.results[0].message_id, { EX: 86400 });
}Per-recipient personalization at scale
For bulk sends with per-recipient variables, use /send-bulk:
await send.partnerEmailSendBulkPost({
body: {
from: "[email protected]",
template_name: "newsletter-june",
default_template_data: { campaign: "june-2026" },
destinations: users.map((u) => ({
to: [u.email],
replacement_data: {
first_name: u.firstName,
unsubscribe_url: `https://yoursite.com/u/${u.token}`,
},
})),
},
});50 destinations × 50 recipients × 500 total per request. For
larger volumes, chunk into multiple calls. There's no per-second
limit on sends, only your account's daily limit: past it a call
stops with 429 until midnight UTC.
Dynamic from-name
Set the from field as "Display Name <[email protected]>" and
recipients see "Display Name" in their inbox:
{
"from": "Sarah from Acme <[email protected]>",
"to": ["[email protected]"],
"subject": "Your order has shipped",
"html_body": "<p>It is on the way.</p>"
}Domain still has to be verified. Display name is unverified —
recipients see whatever you put there. Quote a name that holds a
comma: "Acme, Inc" <[email protected]>.
Custom MAIL FROM domain (return-path)
Add a bounce domain
to a verified domain and the return-path moves to bounce. plus your
domain, so DMARC alignment includes both DKIM and SPF. Until then the
return-path is on our shared domain and DMARC alignment relies on DKIM
only (p=quarantine is fine; p=reject may need DMARC relaxed
alignment).
Per-customer attribution
If you're sending on behalf of multiple downstream customers, create a configuration set per customer and reference it on every send:
await send.partnerEmailSendPost({
body: {
from: "[email protected]",
to: ["[email protected]"],
subject: "Your weekly report",
html_body: "<p>Your report is ready.</p>",
configuration_set_name: "customer_acme_corp",
},
});Stats roll up per config set: pass the set's config_set_id (a UUID,
not its name) to GET /stats?config_set_id=.... Each config set can
also have its own webhook destination so events for
Acme go to one URL and events for Globex go to another.
Hard-bounce auto-list-cleaning
Hard bounces are added to your suppression list automatically. To
keep your application's email list in sync, listen for the
Bounce webhook event:
app.post("/webhooks/splashify", async (req, res) => {
const sig = req.header("x-splashify-signature");
if (!verifyHMAC(req.rawBody, sig, process.env.SPLASHIFY_WEBHOOK_SECRET)) {
return res.status(401).end();
}
if (req.body.eventType === "Bounce" && req.body.bounce.bounceType === "Permanent") {
const email = req.body.bounce.bouncedRecipients[0].emailAddress;
await db.users.updateOne({ email }, { $set: { emailBouncedHard: true } });
}
res.status(200).end();
});Now your signup form / re-engagement campaigns can skip these addresses up-front instead of burning send quota.
Retry on 5xx
Network blips and brief upstream issues should retry; auth/quota
errors shouldn't. Go by the status: retry 429 and 5xx, stop on
every other 4xx. The daily caps are 429 too, but they only clear
when the cap resets, so stop on those as well.
const DAILY_CAPS = ["SANDBOX_QUOTA_REACHED", "DAILY_LIMIT_REACHED"];
async function sendWithRetry(payload, attempts = 3) {
for (let i = 0; i < attempts; i++) {
const res = await fetch("https://api.splashifypro.com/api/v1/partner/email/send", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SPLASHIFY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify(payload),
});
if (res.ok) return res.json();
const err = await res.json().catch(() => ({}));
const retry = res.status >= 500 || (res.status === 429 && !DAILY_CAPS.includes(err.error));
if (!retry) throw new Error(`${err.error}: ${err.message}`);
// Backoff, or the wait a rate limit asks for.
const wait = err.retry_after ? err.retry_after * 1000 : 1000 * Math.pow(2, i);
await new Promise((done) => setTimeout(done, wait));
}
throw new Error("send_failed_after_retries");
}/send isn't idempotent, and a 5xx can come after some recipients
of the call were queued. Send to one recipient per call if you retry.
Webhooks that survive your deploys
Stamp every event in your local DB before processing — duplicate webhook deliveries (which happen on retries) are idempotent:
const eventID = `${req.body.mail.messageId}:${req.body.eventType}`;
const inserted = await db.events.insertOne({
_id: eventID,
...req.body,
}, { ignoreDuplicates: true });
if (!inserted.insertedCount) return res.status(200).end(); // dedup
// ... processX-Splashify-Delivery-ID is a fresh UUID per delivery attempt, so a
retried event has a new one. Dedup on the body fields instead.
Cold-start IP warm-up
New production accounts inherit warm sending infrastructure with established reputation across major mailbox providers. You don't need to manually warm up.
A dedicated IP is new, so it warms up: for the first 14 days its daily volume grows step by step, and we hold back what is over the day's cap and send it later.