Email API Quickstart for Node.js

You’re now ready to write some code. First, create a file in your project directory. Again, you can use index.js because that’s the name of the "main" entry point file in the package.json file.

The following Node.js block contains all the code needed to successfully deliver a message with the SendGrid Mail Send API. You can copy this code, modify the to and from fields, and run the code if you like. We’ll break down each piece of this code in the following sections.

const sgMail = require('@sendgrid/mail')
sgMail.setApiKey(process.env.SENDGRID_API_KEY)

const msg = {
  to: '[email protected]', // Change to your recipient
  from: '[email protected]', // Change to your verified sender
  subject: 'Sending with SendGrid is Fun',
  text: 'and easy to do anywhere, even with Node.js',
  html: '<strong>and easy to do anywhere, even with Node.js</strong>',
}

sgMail
  .send(msg)
  .then((response) => {
    console.log(response[0].statusCode)
    console.log(response[0].headers)
  })
  .catch((error) => {
    console.error(error)
  })

Your API call must have the following components:

• A host (the host for Web API v3 requests is always https://api.sendgrid.com/v3/)
• An API key passed in an Authorization Header
• A request (when submitting data to a resource via POST or PUT, you must submit your request body in JSON format)

In your index.js file, require the Node.js helper library. The library will handle setting the Host, https://api.sendgrid.com/v3/, for you.

const sgMail = require('@sendgrid/mail')

Next, use the API key you set up earlier. Remember, the API key is stored in an environment variable, so you can use the process.env() method to access and assign it using the helper library’s setApiKey() method. The helper library will pass your key to the API in an Authorization header using Bearer token authentication.

sgMail.setApiKey(process.env.SENDGRID_API_KEY)

Now you’re ready to set up your "to", "from", "subject", and message body "text". These values are passed to the API in a “personalizations” object when using the v3 Mail Send API. The helper library allows you to store all this data in a single flat JavaScript object. Assign the object to a variable named msg.

Change the “to” value to a valid email address you can access. This is where your message will be delivered. Change the “from” value to the address you verified during the Sender Identity set up.

The "subject" can be any text. The email body can be either plain text or HTML. The helper library allows you to specify the type of email body by using either the "text" or "html" properties.

const msg = {
  to: '[email protected]', // Change to your recipient
  from: '[email protected]', // Change to your verified sender
  subject: 'Sending with SendGrid is Fun',
  text: 'and easy to do anywhere, even with Node.js',
  html: '<strong>and easy to do anywhere, even with Node.js</strong>',
}

To send the message, pass the msg object as an argument to the helper library’s send() method. You can also add then() and catch() methods to log the response status code and headers or catch and log any errors.

sgMail
  .send(msg)
  .then((response) => {
    console.log(response[0].statusCode)
    console.log(response[0].headers)
  })
  .catch((error) => {
    console.error(error)
  })

The code block is now complete. To send the message, you can run the index.js file with Node.js.

node index.js

If you receive a 202 status code printed to the console, your message was sent successfully. Check the inbox of the “to” address, and you should see your demo message.

If you don’t see the email, you may need to check your spam folder.

If you receive an error message, you can reference our response message documentation for clues about what may have gone wrong.

All responses are returned in JSON format. We specify this by sending the Content-Type header. The Web API v3 provides a selection of response codes, content-type headers, and pagination options to help you interpret the responses to your API requests.