Skip to main content

@sendgrid/mail

PropertyValue
Package@sendgrid/mail
Versions Covered>=7.0.0 <9.0.0
Contract Version1.0.0
Statusproduction
Last Verified2026-02-24
Maintainercorpus-team

Installation​

npm install @sendgrid/mail

Covered Functions​

This contract covers 3 function(s):

send()​

Sends a single email via SendGrid API

Import:

import { send } from '@sendgrid/mail';

Postconditions​

What happens after calling this function:

🔴 ERROR - send-no-try-catch

Condition: send() called without try-catch or .catch() handler

Throws: Error with error.response.body containing API error details

Required Handling:

MUST wrap await sgMail.send() in try-catch block, or use .catch() to handle promise rejection. Catch block should check error.response.body for detailed API error information.

📖 Source

⚠️ WARNING - send-no-error-response-check

Condition: send() in try-catch but catch does not check error.response

Required Handling:

SHOULD check for error.response existence and log error.response.body for detailed API error information. This helps distinguish between network errors (no response) and API errors (response with error details).

📖 Source

sendMultiple()​

Sends multiple emails in parallel via SendGrid API

Import:

import { sendMultiple } from '@sendgrid/mail';

Postconditions​

What happens after calling this function:

🔴 ERROR - send-multiple-no-try-catch

Condition: sendMultiple() called without try-catch or .catch() handler

Throws: Error with error.response.body containing API error details

Required Handling:

MUST wrap await sgMail.sendMultiple() in try-catch block. Should implement rate limiting protection and retry logic for 429 errors. Check error.response.body for detailed error information.

📖 Source

setApiKey()​

Configures SendGrid API key for authentication

Import:

import { setApiKey } from '@sendgrid/mail';

Postconditions​

What happens after calling this function:

⚠️ WARNING - api-key-not-validated

Condition: setApiKey() called without trimming or validating API key

Required Handling:

SHOULD trim whitespace from API key using .trim() and validate key exists before setting: process.env.SENDGRID_API_KEY?.trim() || throw error

📖 Source

Example: Proper Error Handling​

import mail from '@sendgrid/mail';

async function example() {
  try {
    const result = await send(/* args */);
    // Handle success
    return result;
  } catch (error) {
    // Handle error according to contract postconditions
    console.error('Error:', error);
    throw error;
  }
}

See Also​