The SendHeron Node SDK

Your first send

import { SendHeron } from 'sendheron';

const sendheron = new SendHeron(process.env.SENDHERON_API_KEY);

const { data, error } = await sendheron.emails.sendTemplate({
  to: '[email protected]',
  templateId: '550e8400-e29b-41d4-a716-446655440000',
  variables: { orderId: '42' },
});

// A transport or request failure, after the SDK has already retried
// whatever was safe to retry.
if (error) throw error;

if (data.status === 'suppressed') {
  // We refused to send, and data.errorMessage says why in a stable
  // value such as 'HARD_SUPPRESSED'. Never retry this one.
  log.warn('send refused', { reason: data.errorMessage });
} else if (data.status === 'queued') {
  // Waiting for daily sending capacity or new-sender warm-up. It goes
  // out by itself and turns 'sent' on this same record, so keep
  // data.id and do not send it again.
  await orders.recordPendingReceipt(data.id);
} else {
  // Accepted by the provider. Keep both ids: data.id reads the send
  // back later, providerMessageId ties it to provider logs.
  await orders.recordReceipt(data.id, data.providerMessageId);
}

The key comes from SENDHERON_API_KEY if you do not pass one. The base URL, the per-attempt timeout and the retry count are all constructor options, and every one of them has a working default.

Idempotency, when it is your business rule

The SDK handles retry safety on its own. The one thing it cannot guess is whether two calls from your code are the same logical send, which is what your own key is for.

// The SDK generates a key for every send and reuses it across its own
// retries. Pass your own when the DEDUPLICATION is a business fact:
// this receipt should exist once per order, no matter how many times
// your job runner wakes up.
const { data, error } = await sendheron.emails.sendTemplate(
  { to: customer.email, templateId: RECEIPT_TEMPLATE, variables },
  { idempotencyKey: `receipt-${order.id}` },
);

// When the SDK has exhausted its own retries, error.retryable says
// whether trying again later can work: true for a 429, a 5xx, a
// timeout or a network failure, false for a 4xx, which fails the same
// way every time. Resume a retryable send with the SAME key rather
// than minting a fresh one, which could double-send.
if (error?.retryable) {
  await queue.retryLater({ idempotencyKey: error.idempotencyKey });
} else if (error) {
  throw error;
}

Whose problem a refusal is

Every reason belongs to one of two groups, and the package exports both. SENDER_SIDE_BLOCK_REASONS are your own account's configuration or state, such as an unverified From domain, a workspace with no sender identity, paused sending, or an account still waiting for its sending review. Alert on those and fix the setup, and keep the address, which did nothing wrong. RECIPIENT_BLOCK_REASONS are facts about the address, such as a bounce, a spam complaint or an opt-out: surface them and never retry them. isSenderSideBlock(reason) tells the two apart, and treats a reason it does not know as recipient-side, the direction that never retries, so a new grouping reaches you with a package update.

import { SendHeron, isSenderSideBlock } from 'sendheron';

const sendheron = new SendHeron(process.env.SENDHERON_API_KEY);

const { data, error } = await sendheron.emails.sendTemplate({
  to: '[email protected]',
  templateId: '550e8400-e29b-41d4-a716-446655440000',
  variables: { orderId: '42' },
});

if (error) throw error;

if (data.status === 'suppressed') {
  if (isSenderSideBlock(data.errorMessage)) {
    // Our own account, not the recipient: alert, fix the setup, keep
    // the address. SENDER_UNDER_REVIEW lands here until the
    // organization is approved as a sender.
    const { data: usage } = await sendheron.usage.get();
    console.warn('send refused on our side', {
      reason: data.errorMessage,
      sendingReview: usage?.plan.sendingReview,
    });
  } else {
    // A fact about the address: a bounce, a complaint, an opt-out, or
    // a reason this version of the package does not know yet.
    // Surface it and never retry it.
    console.info('this address will not get the mail', {
      to: data.to,
      reason: data.errorMessage,
    });
  }
}

SENDER_UNDER_REVIEW is the sender-side reason a new account meets first. Until a person at SendHeron approves the organization as a sender, it reaches only team members who have confirmed their email address and addresses on its own verified domains, and every other send is suppressed with this reason, transactional mail included. Retrying does not help: read plan.sendingReview from usage.get(), which is SANDBOX, REQUESTED or APPROVED, and have the account owner ask for the review from the getting-started card in the dashboard. A send refused before approval is not replayed afterwards. Send it again, with a new idempotency key if you pass your own, because a reused key replays the recorded refusal.