Node.js SDK

The SDK gives every endpoint of this API as a typed method. It has no dependencies, works with TypeScript and JavaScript, and retries a failed request without ever sending a message twice.

npm install @wesend/node

Quick start

Keep your API key in the WESEND_API_KEY environment variable. Called with no key, as new WeSend(), the client reads it from there itself.

import { WeSend } from "@wesend/node"

const wesend = new WeSend(process.env.WESEND_API_KEY)

const message = await wesend.sms.send({
  to: "99112233",
  text: "Tanii zahialga batalgaajlaa. #1042",
})

console.log(message.id, message.status, message.balance)

Methods

Each method calls one endpoint and returns its response. Fields are named exactly as on the endpoint pages (from_name, batch_id, created_at); only the SDK's own options are camelCase (idempotencyKey, maxRetries).

On every endpoint page, the Node.js tab of a request example shows the SDK call.

Errors

A failed request throws a WeSendError. Branch on its code, which is one of the codes on the Errors page. Use message only for logs.

import { WeSend, WeSendError } from "@wesend/node"

try {
  await wesend.sms.send({ to: "99112233", text: "Sain baina uu" })
} catch (error) {
  if (!(error instanceof WeSendError)) throw error

  if (error.code === "insufficient_credits") {
    console.log(`Need ${error.required} credits, have ${error.balance}`)
  } else {
    console.error(error.status, error.code, error.message)
  }
}

• verify.check resolves when the code is right. A wrong code throws invalid_code, with the tries left in attempts_remaining.
• Three codes come from the SDK itself and not from the API: timeout and connection_error (no answer arrived, so status is null), and unexpected_response (the answer did not come from the WeSend API).

Retries and idempotency

The SDK tries a failed request again by itself, up to 2 more times, whenever that cannot send a message twice.

The four send methods (sms.send, sms.sendBulk, email.send, email.sendBulk) always carry an Idempotency-Key: the SDK makes one for each call, so its own retries never send twice. Pass your own key to stay safe when your code runs twice too, such as a queue job that is retried.

await wesend.sms.send(
  { to: "99112233", text: "Tanii zahialga batalgaajlaa. #1042" },
  { idempotencyKey: "order-1042-confirmation" },
)

• With your own key, a 502 provider_failed is not retried: a repeat under that key would only report the same failure. Send again with a new key.
• verify.create and verify.check take no Idempotency-Key, so they are not retried after a network failure or a 5xx.

Options

const wesend = new WeSend(process.env.WESEND_API_KEY, {
  timeout: 30_000,
  maxRetries: 2,
})