Skip to content
Splashify Pro
Email docsEmail

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:

javascript
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:

javascript
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:

javascript
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:

json
{
  "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:

javascript
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:

javascript
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.

javascript
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:

javascript
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
// ... process

X-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.