SendGrid Email
Configure SendGrid when you need advanced delivery controls and template support.
Use SendGrid when you need the broadest set of delivery controls. ViteHub maps the shared email surface into SendGrid's mail send payload so your authored emails stay portable.
Install the SDK
Terminal
pnpm add https://pkg.pr.new/vite-hub/vitehub/@vitehub/email@main @sendgrid/mail
Set SENDGRID_API_KEY in the runtime environment, or pass email.apiKey directly in config.
Configure SendGrid
nuxt.config.ts
export default defineNuxtConfig({
modules: ['@vitehub/email/nuxt'],
email: {
provider: 'sendgrid',
apiKey: process.env.SENDGRID_API_KEY,
defaults: {
from: 'Acme <hello@example.com>',
},
},
})
Send with SendGrid
Use the shared ViteHub email shape for template sends or direct HTML sends.
const email = await createEmailClient()
await email.send({
from: 'Acme <hello@example.com>',
to: 'max@example.com',
metadata: {
audience: 'onboarding',
},
delivery: {
labels: ['welcome'],
scheduleAt: new Date(Date.now() + 60_000),
template: {
key: 'd-welcome-template',
data: { name: 'Max' },
},
},
})
What changes on SendGrid
| Concern | Behavior |
|---|---|
metadata | ViteHub maps metadata to customArgs. |
delivery.labels | ViteHub maps labels to categories. |
delivery.template.key | ViteHub maps the template key to templateId. |
delivery.template.data | ViteHub maps template data to dynamicTemplateData. |
delivery.scheduleAt | ViteHub maps the scheduled date to sendAt. |
| Batch sending | SendGrid sends batches as fanout requests through the SDK's send() method. |
Use delivery.transport for SendGrid-only payload fields such as ASM, mail settings, personalizations, sections, substitutions, or tracking settings.
const email = await createEmailClient()
await email.send({
from: 'Acme <hello@example.com>',
to: 'max@example.com',
subject: 'Welcome',
html: '<p>Welcome</p>',
text: 'Welcome',
delivery: {
labels: ['welcome'],
transport: {
asm: { groupId: 7 },
batchId: 'batch-1',
trackingSettings: {
clickTracking: { enable: true },
},
},
},
})
delivery.transport is applied after the shared field mapping, so it can override categories, templateId, dynamicTemplateData, or any other SendGrid payload field when you need to drop down to the provider API.
Choose SendGrid when you need advanced mail controls, dynamic templates, and a provider payload that you can still override directly.