Helo

Capabilities

These values come from the adapter's exported capabilities declaration. The field support matrix covers normalized message fields.

The Helo adapter calls POST /send/transactional on the Helo API with plain fetch and Bearer authentication. Helo groups sending into Channels, and the adapter can pin every send to one Channel.

Helo@opencoredev/email-sdk/helo

Provider docs

Configure

Create an API credential in Helo and verify the domain you send from.

import { createEmailClient } from "@opencoredev/email-sdk";
import { helo } from "@opencoredev/email-sdk/helo";

export const email = createEmailClient({
  adapters: [
    helo({
      apiKey: process.env.HELO_API_KEY!,
      channelId: process.env.HELO_CHANNEL_ID,
    }),
  ],
});

Send

The adapter maps cc, bcc, replyTo, custom headers, attachments, tags, and metadata. An attachment goes out inline when it has a contentId or disposition: "inline".

const result = await email.send({
  from: "Acme <hello@acme.com>",
  to: "user@example.com",
  replyTo: "support@example.com",
  subject: "Your invoice is ready",
  html: "<p>Your March invoice is attached.</p>",
  attachments: [
    { filename: "invoice.pdf", content: pdfBytes, contentType: "application/pdf" },
  ],
  tags: [{ name: "type", value: "invoice" }],
  metadata: { invoiceId: "inv_123" },
});

console.log(result.id); // Helo message id

Helo tags are plain strings, so the adapter sends each tag's value and drops its name. Metadata values are sent as strings: numbers and booleans are converted, and null becomes an empty string.

Helo has no scheduled sending. A message with sendAt throws an EmailValidationError.

The client's idempotency key goes out as the X-Helo-Idempotency-Key header. Helo accepts keys up to 36 characters. Longer keys, such as the per-recipient keys sendPersonalized derives, are hashed into a UUID-shaped SHA-256 digest, so the same client key always maps to the same Helo key.

Failed sends

Helo can answer HTTP 200 with status: "failed" and an errorCode. That message was never queued, so the adapter throws an EmailAdapterError with retryable: false and delivery: "not_sent", and includes Helo's reason in the error message.

Other 4xx responses are reported with delivery: "not_sent". A 409 or 5xx response reports delivery: "unknown", because a 409 can mean another request with the same idempotency key is still in flight.

Verify from the CLI

HELO_API_KEY="..." npx --package @opencoredev/email-sdk email-sdk doctor --adapter helo --live

The live check posts an empty body to /send/transactional. Once the credential authenticates, Helo rejects the request with a 422 validation_failed or invalid_channel error, which the check reports as authenticated. Nothing is sent.

HELO_API_KEY="..." npx --package @opencoredev/email-sdk email-sdk send \
  --adapter helo \
  --channel-id "$HELO_CHANNEL_ID" \
  --from "Acme <hello@acme.com>" \
  --to user@example.com \
  --subject "Helo smoke test" \
  --html "<p>It works</p>" \
  --dry-run

Drop --dry-run to send for real. The CLI also reads HELO_CHANNEL_ID and HELO_BASE_URL from the environment. Failed requests surface Helo's error detail, any field errors, and its error code.