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

tsx
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)

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

bash
# After editing webiny.config.tsx, build the API
yarn webiny build api

> Note: This command only works in a dev environment. For other environments, run yarn webiny build api --env=YOUR_ENV instead.

ts
// Environment variable in .env
SMTP_PASSWORD = your - smtp - password - here;

Related Skills

• webiny-project-structure — Where webiny.config.tsx lives and how extensions are structured
• webiny-local-development — Running and deploying locally