Generic Node.js REST Client

Common errors

• TypeError: sendgrid_rest__WEBPACK_IMPORTED_MODULE_0__.Client is not a constructor

  cause This error typically occurs in environments (like modern bundlers or TypeScript projects) attempting to import a CommonJS-only library using ES module `import` syntax.
  fix Ensure you are using `const Client = require('sendgrid-rest').Client;` in CommonJS contexts. If using TypeScript with `esModuleInterop` enabled, configure your `tsconfig.json` or adjust import paths. For modern applications, migrating to `@sendgrid/client` or another ESM-compatible HTTP client is recommended.

• Error: unable to get local issuer certificate (or similar SSL/TLS error)

  cause Older Node.js versions or outdated SSL/TLS configurations in the underlying HTTP client can struggle with modern certificate chains, especially in corporate networks or when interacting with newer APIs.
  fix Update your Node.js environment to a more recent, officially supported LTS version. Ensure your system's certificate authorities are up to date. If behind a corporate proxy, configure Node.js to trust the proxy's certificates (`NODE_TLS_REJECT_UNAUTHORIZED=0` is a workaround but insecure for production).

• Callback function not invoked / Request timed out

  cause This indicates network issues, a slow or unresponsive API server, or incorrect `request.host` or `request.path` configuration preventing the HTTP request from completing or reaching its destination.
  fix Verify `request.host` and `request.path` are correct. Check network connectivity to the target API. Inspect server logs if you control the API. Implement robust error handling within the callback function and consider adding manual timeouts if the client doesn't provide them.

Warnings

• breaking The `sendgrid-rest` repository is explicitly no longer maintained by SendGrid. Users are advised to migrate to `@sendgrid/client` (part of the `sendgrid-nodejs` monorepo) for active development, support, and modern features.
  Fix: Migrate your usage to the `@sendgrid/client` package, which offers a Promise-based API and is actively maintained. Install with `npm install @sendgrid/client`.
• breaking This library officially supports very old Node.js versions (0.10, 0.12, 4). Using it with modern Node.js versions (e.g., Node 16+) may lead to compatibility issues, unexpected behavior, or security vulnerabilities due to underlying system changes or unpatched dependencies.
  Fix: It is strongly recommended to migrate to a modern, actively maintained HTTP client library (like `axios`, `node-fetch`, or `@sendgrid/client`) that explicitly supports your Node.js version. If forced to use, thoroughly test against your target Node.js runtime.
• gotcha The API uses a traditional Node.js callback pattern, which can lead to 'callback hell' in complex asynchronous flows and does not integrate naturally with modern `Promise`-based or `async/await` patterns. Error handling is also tied to this callback.
  Fix: Consider migrating to an HTTP client that offers native Promise support for better async control and cleaner code with `async/await`. Manual promisification is possible but adds boilerplate.
• deprecated While `sendgrid-rest` is a generic HTTP client, many users might encounter it searching for SendGrid API integration. SendGrid officially discontinued its free email plan as of July 26, 2025. This means any SendGrid API calls (regardless of client library) made from accounts on the free tier will fail.
  Fix: If using SendGrid's email service, ensure your SendGrid account is on a paid plan to continue sending emails. This warning is specific to SendGrid API usage, not the `sendgrid-rest` library itself.

Install

• npm install sendgrid-rest npm
• yarn add sendgrid-rest yarn
• pnpm add sendgrid-rest pnpm

Imports

• Client
  wrong:

  import { Client } from 'sendgrid-rest';

  correct:

  const Client = require('sendgrid-rest').Client;

  This library is CommonJS-only and does not support ES modules. Direct destructuring of `require('sendgrid-rest')` is also common for `Client`.
• Client
  wrong:

  import { Client } from 'sendgrid-rest'; // When only importing types

  correct:

  import type { Client } from 'sendgrid-rest';

  TypeScript type definitions for `Client` were added in v2.6.0. Use `import type` for type-only imports to prevent accidental runtime imports in some bundlers.
• Request (type)

  import type { Request } from 'sendgrid-rest';

  The `Request` object structure is an important type for defining HTTP calls with this client. It is used as a type, not a runtime value.

Quickstart

Demonstrates how to make a POST request to a hypothetical REST API, including setting headers, query parameters, and a JSON request body using the callback-based API.

const Client = require('sendgrid-rest').Client;
const client = new Client();
const request = client.emptyRequest();
const param = 'myparam';

request.host = 'api.example.com';
request.headers['Authorization'] = 'Bearer XXXXXX'; // Replace XXXXXX with your actual token
request.queryParams['limit'] = 100;
request.queryParams['offset'] = 0;
request.method = 'POST';
request.path = '/your/api/' + param + '/call';

const requestBody = {
  'some': 0,
  'awesome': 1,
  'data': 3
};
request.body = requestBody;

client.API(request, function (response) {
  console.log('Status Code:', response.statusCode);
  console.log('Response Body:', response.body);
  console.log('Response Headers:', response.headers);

  if (response.statusCode >= 400) {
    console.error('API Error:', response.body);
  }
});