Email

Send emails through SMTP, SendGrid, or Amazon SES with template support.

Providers

Provider	Configuration Key	Description
smtp	SMTP host/port/auth	Standard SMTP relay
sendgrid	SendGrid API key	SendGrid transactional email
ses	AWS credentials	Amazon Simple Email Service

Configuration

SMTP

messaging({
  email: {
    provider: "smtp",
    host: "smtp.gmail.com",
    port: 587,
    secure: false,
    auth: {
      user: "your@gmail.com",
      pass: "app-password",
    },
    from: "Your App <noreply@yourapp.com>",
  },
});

SendGrid

messaging({
  email: {
    provider: "sendgrid",
    apiKey: process.env.SENDGRID_API_KEY,
    from: "noreply@yourapp.com",
  },
});

Amazon SES

messaging({
  email: {
    provider: "ses",
    region: "us-east-1",
    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
    from: "noreply@yourapp.com",
  },
});

Sending Emails

Simple Email

await app.messaging.email.send({
  to: "user@example.com",
  subject: "Welcome!",
  body: "<h1>Welcome to our platform</h1><p>Thanks for signing up.</p>",
});

With Attachments

await app.messaging.email.send({
  to: "user@example.com",
  subject: "Your Invoice",
  body: "<p>Please find your invoice attached.</p>",
  attachments: [
    {
      filename: "invoice.pdf",
      content: pdfBuffer,
      contentType: "application/pdf",
    },
  ],
});

Multiple Recipients

await app.messaging.email.send({
  to: ["alice@example.com", "bob@example.com"],
  cc: ["manager@example.com"],
  bcc: ["audit@example.com"],
  subject: "Team Update",
  body: "<p>Here is the weekly update.</p>",
});

Using Templates

// Register a template
app.messaging.email.registerTemplate("welcome", {
  subject: "Welcome, {{name}}!",
  body: `
    <h1>Welcome, {{name}}!</h1>
    <p>Thanks for joining {{appName}}.</p>
    <a href="{{verifyUrl}}">Verify your email</a>
  `,
});

// Send using the template
await app.messaging.email.sendTemplate("welcome", {
  to: "alice@example.com",
  data: {
    name: "Alice",
    appName: "My App",
    verifyUrl: "https://myapp.com/verify?token=abc123",
  },
});

API Reference

email.send(options): Promise<MessageResult>

Option	Type	Required	Description
to	string | string[]	Yes	Recipient(s)
subject	string	Yes	Email subject
body	string	Yes	HTML body
text	string	No	Plain text body
from	string	No	Override sender
cc	string | string[]	No	CC recipients
bcc	string | string[]	No	BCC recipients
replyTo	string	No	Reply-to address
attachments	Attachment[]	No	File attachments

email.sendTemplate(name, options): Promise<MessageResult>

Send using a registered template.

email.registerTemplate(name, template): void

Register a reusable email template with {{variable}} placeholders.

REST API

curl -X POST http://localhost:3000/messaging/email \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGci..." \
  -d '{
    "to": "user@example.com",
    "subject": "Hello",
    "body": "<p>Hello from FluxKit!</p>"
  }'

Response (200):

{
  "messageId": "abc123",
  "status": "sent",
  "channel": "email",
  "to": "user@example.com"
}