@api-buddy/sendgrid NPM

@api-buddy/sendgrid

A comprehensive SendGrid integration for Next.js applications, providing a simple and type-safe way to send transactional and marketing emails.

Features

🚀 Easy Setup: Get started quickly with a few simple steps
🔒 Type-Safe: Full TypeScript support for all email options and responses
⚡ Performance Optimized: Efficient email sending with proper error handling
🎣 React Hooks: Custom hooks for easy email sending from React components
🛠 CLI Tool: Quick project setup with the included CLI
📧 Templates Support: Built-in support for SendGrid's dynamic templates
📊 Analytics: Track email opens, clicks, and other events

Installation

# Using npm
npm install @api-buddy/sendgrid @sendgrid/mail

# Using yarn
yarn add @api-buddy/sendgrid @sendgrid/mail

# Using pnpm
pnpm add @api-buddy/sendgrid @sendgrid/mail

Quick Start

1. Set Up Environment Variables

Create a .env.local file in your project root and add your SendGrid API key:

SENDGRID_API_KEY=your_sendgrid_api_key_here
SENDGRID_FROM_EMAIL=your-email@example.com

2. Initialize SendGrid in Your Next.js App

Wrap your application with the SendGridProvider in your root layout:

// app/layout.tsx
'use client';

import { SendGridProvider } from '@api-buddy/sendgrid';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <SendGridProvider 
          config={{
            // Optional: Configure default settings here
            defaultFrom: 'noreply@yourdomain.com',
            defaultReplyTo: 'support@yourdomain.com',
          }}
        >
          {children}
        </SendGridProvider>
      </body>
    </html>
  );
}

3. Send Your First Email

Create an API route to handle email sending:

// app/api/email/route.ts
import { NextResponse } from 'next/server';
import { sendEmail } from '@api-buddy/sendgrid';

export async function POST(request: Request) {
  try {
    const { to, subject, text, html } = await request.json();
    
    const result = await sendEmail({
      to,
      from: 'noreply@yourdomain.com',
      subject,
      text,
      html,
    });
    
    return NextResponse.json({ success: true, data: result });
  } catch (error) {
    console.error('Error sending email:', error);
    return NextResponse.json(
      { success: false, error: 'Failed to send email' },
      { status: 500 }
    );
  }
}

4. Use the useEmail Hook in Your Components

'use client';

import { useEmail } from '../hooks/useEmail';

export function ContactForm() {
  const { sendEmail, isLoading, error } = useEmail();
  
  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    
    try {
      await sendEmail({
        to: 'contact@yourdomain.com',
        subject: 'New Contact Form Submission',
        text: 'Hello from the contact form!',
        html: '<p>Hello from the contact form!</p>',
      });
      
      alert('Message sent successfully!');
    } catch (err) {
      console.error('Failed to send message:', err);
      alert('Failed to send message. Please try again.');
    }
  };
  
  return (
    <form onSubmit={handleSubmit}>
      {/* Your form fields */}
      <button type="submit" disabled={isLoading}>
        {isLoading ? 'Sending...' : 'Send Message'}
      </button>
      {error && <div className="error">{error.message}</div>}
    </form>
  );
}

CLI Setup

For a quick setup, use the included CLI:

npx @api-buddy/sendgrid

This will: 1. Install required dependencies 2. Create an API route for sending emails 3. Generate a custom useEmail hook 4. Set up an example contact form component 5. Update your environment variables

API Reference

`SendGridProvider`

A context provider that makes the SendGrid client available throughout your application.

Props

config: Configuration object
- apiKey: Your SendGrid API key (optional, defaults to process.env.SENDGRID_API_KEY)
- defaultFrom: Default "from" email address
- defaultReplyTo: Default "reply to" email address
- mailSettings: Default mail settings for all emails
- trackingSettings: Default tracking settings for all emails
- asm: Default ASM (Advanced Suppression Manager) settings
- ipPoolName: Default IP pool name

`useSendGrid()`

A hook to access the SendGrid client and config from the nearest SendGridProvider.

Returns

client: The SendGrid client instance
config: The current SendGrid configuration

`sendEmail(options: EmailOptions): Promise<SendGridResponse>`

Send an email using SendGrid.

Parameters

options: Email options
- to: Recipient email address or array of email addresses
- from: Sender email address
- subject: Email subject
- text: Plain text content
- html: HTML content
- templateId: SendGrid template ID
- dynamicTemplateData: Dynamic template data
- attachments: Email attachments
- categories: Email categories for tracking
- customArgs: Custom arguments
- headers: Custom headers
- mailSettings: Mail settings
- trackingSettings: Tracking settings
- replyTo: Reply-to email address
- sendAt: Send at timestamp (Unix timestamp)
- batchId: Batch ID for scheduling
- asm: ASM (Advanced Suppression Manager) settings
- ipPoolName: IP pool name

Returns

A promise that resolves to the SendGrid API response.

`useEmail()`

A hook for sending emails from React components.

Returns

sendEmail: Function to send an email
isLoading: Boolean indicating if an email is being sent
error: Error object if sending failed
reset: Function to reset the hook state

Examples

Sending a Simple Email

import { sendEmail } from '@api-buddy/sendgrid';

// In an API route or server component
await sendEmail({
  to: 'recipient@example.com',
  from: 'sender@example.com',
  subject: 'Hello from SendGrid',
  text: 'This is a test email',
  html: '<p>This is a test email</p>',
});

Using Dynamic Templates

await sendEmail({
  to: 'recipient@example.com',
  from: 'sender@example.com',
  templateId: 'd-1234567890abcdef1234567890abcdef',
  dynamicTemplateData: {
    name: 'John Doe',
    verificationLink: 'https://example.com/verify?token=abc123',
  },
});

Sending to Multiple Recipients

await sendEmail({
  to: ['user1@example.com', 'user2@example.com'],
  from: 'sender@example.com',
  subject: 'Hello everyone!',
  text: 'This email is sent to multiple recipients',
});

Error Handling

All email sending methods throw a SendGridApiError when something goes wrong. You can catch and handle these errors:

try {
  await sendEmail({
    // ...
  });
} catch (error) {
  if (error.isRateLimit) {
    console.error('Rate limit exceeded:', error.message);
  } else if (error.isAuthError) {
    console.error('Authentication error:', error.message);
  } else {
    console.error('Error sending email:', error.message);
  }
}

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

MIT

Acknowledgments

SendGrid - Email delivery service
@sendgrid/mail - Official SendGrid Node.js library

sendgrid email transactional marketing nextjs api

4 months ago

4 months ago

4 months ago