Socket
Book a DemoInstallSign in
Socket

@weweb/backend-sendgrid

Package Overview
Dependencies
Maintainers
4
Versions
31
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@weweb/backend-sendgrid

SendGrid integration for WeWeb backend services

0.2.3
latest
npmnpm
Version published
Weekly downloads
12
50%
Maintainers
4
Weekly downloads
 
Created
Source

WeWeb SendGrid Integration

A WeWeb backend integration for SendGrid's email API, providing robust email sending capabilities within WeWeb backend workflows. This integration uses the official @sendgrid/mail and @sendgrid/client packages for reliable email delivery with features like templates, contacts management, and list management.

Features

  • Simple integration with SendGrid's email API
  • Send transactional emails with HTML or plain text content
  • Support for CC, BCC, and reply-to fields
  • Template support with dynamic data
  • Contact and list management
  • Email scheduling and batch sending capabilities
  • Advanced tracking and analytics options

Installation

This package is designed to work with the WeWeb Supabase Backend Builder and Deno.

import { serve } from '@weweb/backend-core';
import { createSendGridIntegration } from '@weweb/backend-sendgrid';

Usage

Basic Setup

import type { BackendConfig } from '@weweb/backend-core';
import { serve } from '@weweb/backend-core';
import SendGrid from '@weweb/backend-sendgrid';

// Define your backend configuration
const config: BackendConfig = {
  workflows: [
    // Your workflows here
  ],
  integrations: [
    // Use the default SendGrid integration
    SendGrid,
    // Or add other integrations
  ],
  production: false,
};

// Start the server
const server = serve(config);

Custom Configuration

You can customize the SendGrid client by using the createSendGridIntegration function:

import { createSendGridIntegration } from '@weweb/backend-sendgrid';

// Create a custom SendGrid integration
const customSendGrid = createSendGridIntegration({
  apiKey: 'SG.xxxxxxxxxxxxxxxx', // Override environment variable
});

If not specified, the integration will use the following environment variable:

  • SENDGRID_API_KEY - Your SendGrid API Key

Available Methods

Send Email

Send transactional emails to one or multiple recipients.

// Example workflow action
const config = {
  type: 'action',
  id: 'send_welcome_email',
  actionId: 'sendgrid.send_email',
  inputMapping: [
    {
      from: { email: 'welcome@yourdomain.com', name: 'Your Company' },
      to: [{ email: '$body.email', name: '$body.name' }],
      subject: 'Welcome to Our Platform',
      html: '<h1>Welcome!</h1><p>Thank you for signing up.</p>',
      text: 'Welcome! Thank you for signing up.'
    }
  ]
};

Using SendGrid templates:

// Example workflow action with template
const config = {
  type: 'action',
  id: 'send_template_email',
  actionId: 'sendgrid.send_email',
  inputMapping: [
    {
      from: { email: 'notifications@yourdomain.com', name: 'Your Company' },
      to: [{ email: '$body.email' }],
      subject: 'Your account has been updated',
      templateId: 'd-f3e13d2c4a8b4e9d8c7b6a5f4e3d2c1b',
      dynamicTemplateData: {
        user_name: '$body.name',
        action_type: '$body.action',
        date: '$body.date'
      }
    }
  ]
};

Contact Management

Working with contacts and lists:

// Create a new list
sendgrid.create_list({ name: 'Newsletter Subscribers' });

// Add contacts to a list
sendgrid.create_contact({
  list_ids: ['list_id_here'],
  contacts: [
    {
      email: 'user@example.com',
      first_name: 'John',
      last_name: 'Doe',
      custom_fields: {
        e1_T: 'Premium', // Custom field for subscription level
        e2_N: 42 // Custom number field
      }
    }
  ]
});

// Get contact information
sendgrid.get_contact({ email: 'user@example.com' });

// Search for contacts
sendgrid.search_contacts({ query: 'last_name = \'Smith\' AND CONTAINS(list_ids, \'list_id_here\')' });

// Delete contacts
sendgrid.delete_contact({
  ids: ['contact_id_1', 'contact_id_2']
  // or use 'emails' field to delete by email address
});

List Management

// Get all lists
sendgrid.get_lists();

// Get a specific list
sendgrid.get_list({ id: 'list_id_here' });

// Delete a list
sendgrid.delete_list({ id: 'list_id_here' });

Template Management

// Get all templates
sendgrid.get_templates({ generations: 'dynamic' });

// Get a specific template
sendgrid.get_template({ id: 'template_id_here' });

Example: Complete Email Service Application

import type { BackendConfig } from '@weweb/backend-core';
import { serve } from '@weweb/backend-core';
import SendGrid from '@weweb/backend-sendgrid';

const config: BackendConfig = {
  workflows: [
    {
      path: '/api/send-email',
      methods: ['POST'],
      security: {
        accessRule: 'public',
      },
      inputsValidation: {
        body: {
          type: 'object',
          properties: {
            to: { type: 'string' },
            name: { type: 'string' },
            subject: { type: 'string' },
            message: { type: 'string' },
            template: { type: 'string', enum: ['welcome', 'password_reset', 'invoice'] }
          },
          required: ['to', 'subject', 'message'],
        },
      },
      workflow: [
        {
          type: 'action',
          id: 'get_template_id',
          actionId: 'core.switch',
          inputMapping: [
            {
              value: '{{ $body.template }}',
              cases: {
                welcome: 'd-welcome-template-id',
                password_reset: 'd-password-reset-template-id',
                invoice: 'd-invoice-template-id'
              },
              default: null
            }
          ],
          outputs: {
            value: 'templateId'
          }
        },
        {
          type: 'action',
          id: 'send_email',
          actionId: 'sendgrid.send_email',
          inputMapping: [
            {
              'from': {
                email: 'support@yourdomain.com',
                name: 'Your Company Support'
              },
              'to': [{
                email: '{{ $body.to }}',
                name: '{{ $body.name }}'
              }],
              'subject': '{{ $body.subject }}',
              'dynamicTemplateData': {
                subject: '{{ $body.subject }}',
                message: '{{ $body.message }}',
                user_name: '{{ $body.name }}'
              },
              // Use template if specified, otherwise use HTML content
              '{{ $steps.get_template_id.outputs.templateId ? "templateId" : "html" }}':
                '{{ $steps.get_template_id.outputs.templateId ? $steps.get_template_id.outputs.templateId : "<h1>" + $body.subject + "</h1><p>" + $body.message + "</p>" }}'
            }
          ]
        }
      ],
    },
    {
      path: '/api/subscribe',
      methods: ['POST'],
      security: {
        accessRule: 'public',
      },
      inputsValidation: {
        body: {
          type: 'object',
          properties: {
            email: { type: 'string' },
            firstName: { type: 'string' },
            lastName: { type: 'string' }
          },
          required: ['email'],
        },
      },
      workflow: [
        {
          type: 'action',
          id: 'add_to_list',
          actionId: 'sendgrid.create_contact',
          inputMapping: [
            {
              list_ids: ['your-list-id-here'],
              contacts: [{
                email: '{{ $body.email }}',
                first_name: '{{ $body.firstName }}',
                last_name: '{{ $body.lastName }}'
              }]
            }
          ]
        },
        {
          type: 'action',
          id: 'send_confirmation',
          actionId: 'sendgrid.send_email',
          inputMapping: [
            {
              from: {
                email: 'newsletter@yourdomain.com',
                name: 'Your Company Newsletter'
              },
              to: [{
                email: '{{ $body.email }}',
                name: '{{ $body.firstName }} {{ $body.lastName }}'
              }],
              subject: 'Newsletter Subscription Confirmation',
              templateId: 'd-your-confirmation-template-id',
              dynamicTemplateData: {
                first_name: '{{ $body.firstName }}'
              }
            }
          ]
        }
      ]
    }
  ],
  integrations: [SendGrid],
  production: false,
};

console.log('Starting email service on http://localhost:8000/api/send-email');
serve(config);

Authentication

This integration uses the official SendGrid client and requires a SendGrid API key to function:

You can get your API key from the SendGrid Dashboard.

Getting Started with SendGrid

  • Create a SendGrid account at sendgrid.com
  • Verify your domain to ensure better deliverability
  • Generate an API key from the dashboard
  • Set the SENDGRID_API_KEY environment variable or provide it in the configuration

SendGrid offers features like:

  • Email analytics and tracking
  • Bounce handling
  • Template management
  • Webhook integration for delivery status
  • Domain verification for improved deliverability
  • Advanced contact management

For full details, see SendGrid's documentation.

FAQs

Package last updated on 09 Jul 2025

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

About

Packages

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc

U.S. Patent No. 12,346,443 & 12,314,394. Other pending.