webiny-mailer-smtp
GitHub用于在 Webiny 项目中配置 SMTP 邮件发送服务。通过在 webiny.config.tsx 中添加 Api.Mailer.Smtp 组件，设置主机、端口、认证及发件人信息，支持环境变量管理密码，确保构建时正确序列化配置。
Trigger Scenarios
Install
npx skills add webiny/webiny-js --skill webiny-mailer-smtp -g -y
SKILL.md
Frontmatter
{
"name": "webiny-mailer-smtp",
"description": "Use when configuring SMTP email\/mailer settings in a Webiny project. Triggers on: \"configure email\", \"set up SMTP\", \"mailer config\", \"sending emails\", \"email not working\", \"configure mailer\", \"SMTP password\", \"Api.Mailer.Smtp\"."
}
Mailer SMTP Configuration
TL;DR
Add <Api.Mailer.Smtp ... /> to your webiny.config.tsx to configure SMTP email delivery at build time. The component serializes the settings into the build artifact — always pass the password via an environment variable, never hard-code it. Deploy the API after making changes.
Core Pattern
import { Api } from "webiny/extensions";
<Api.Mailer.Smtp
host={"smtp.example.com"}
port={587}
user={"smtp-user"}
password={process.env.SMTP_PASSWORD!}
from={"noreply@example.com"}
replyTo={"support@example.com"} {/* optional */}
/>
Place this inside the JSX returned by your config component in webiny.config.tsx, alongside other <Api.*> extensions.
Props Reference
| Prop | Type | Required | Description |
|---|---|---|---|
host |
string |
Yes | SMTP server hostname |
port |
number |
Yes | SMTP server port (positive integer) |
user |
string |
Yes | SMTP authentication username |
password |
string |
Yes | SMTP authentication password — use env var |
from |
string |
Yes | Default sender address |
replyTo |
string |
No | Default reply-to address |
from and replyTo are validated by the email-addresses package against RFC 5322.
Full Example (webiny.config.tsx)
import React from "react";
import { Api, Admin, Core } from "webiny/extensions";
const MyConfig = () => {
return (
<>
{/* ... other extensions ... */}
{/* Mailer: configure SMTP transport via code */}
<Api.Mailer.Smtp
host={"smtp.sendgrid.net"}
port={587}
user={"apikey"}
password={process.env.SENDGRID_API_KEY!}
from={"noreply@acme.com"}
replyTo={"support@acme.com"}
/>
</>
);
};
Add SENDGRID_API_KEY=your-secret to your .env file (never commit it).
Common Mistakes
| Mistake | Fix |
|---|---|
| Hard-coding the password | Use process.env.SMTP_PASSWORD! |
process.env.SMTP_PASSWORD undefined at build time → "expected string, received object" error |
Ensure the env var is set before deploying |
from/replyTo value fails validation |
Must be a valid RFC 5322 mailbox address |
| Settings not taking effect | Run yarn webiny build api after editing webiny.config.tsx |
Quick Reference
# After editing webiny.config.tsx, build the API
yarn webiny build api
Note: This command only works in a
devenvironment. For other environments, runyarn webiny build api --env=YOUR_ENVinstead.
// Environment variable in .env
SMTP_PASSWORD = your - smtp - password - here;
Related Skills
webiny-project-structure— Wherewebiny.config.tsxlives and how extensions are structuredwebiny-local-development— Running and deploying locally
Version History
- 80eb1c5 Current 2026-08-20 10:09
