@weweb/backend-sendgrid

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: '[e-mail]', 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: '[e-mail]', 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: '[e-mail]',
      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: '[e-mail]' });

// 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: '[e-mail]',
                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: '[e-mail]',
                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.