MagicDX

Theme

Magic-Mail — Installation ​

Prerequisites ​

  • Strapi v5.0.0 or higher (v4 is not supported)
  • Node.js 18.x, 20.x, or 22.x
  • Database: SQLite, PostgreSQL, MySQL, or MariaDB (any Strapi-supported database)
  • npm 8+ or yarn 1.22+

1. Install the package ​

bash
npm install strapi-plugin-magic-mail
bash
yarn add strapi-plugin-magic-mail
bash
pnpm add strapi-plugin-magic-mail

2. Enable in your Strapi config ​

Edit (or create) config/plugins.ts:

typescript
export default () => ({
  'magic-mail': {
    enabled: true,
  },
});

That is the minimum. All runtime configuration (accounts, routing rules, templates) lives in the admin UI and is stored in your database.

3. Rebuild the admin panel ​

bash
npm run build
npm run develop

The first npm run develop after install will run migrations and create the necessary tables.

4. Add your first email account ​

  1. Open Strapi admin (typically http://localhost:1337/admin).
  2. In the sidebar click Magic-Mail → Email Accounts.
  3. Click Add Account.
  4. Pick a provider (Gmail OAuth, SMTP, SendGrid, etc.) — see Providers for per-provider setup.
  5. Fill in the credentials and click Test.
  6. Once the test passes, click Save. The account becomes immediately available to the email service.

5. (Recommended) Set an encryption key ​

Without a custom key, Magic-Mail uses Strapi's default encryption. For production, generate your own:

bash
openssl rand -hex 32

Add the output to your .env:

bash
MAGIC_MAIL_ENCRYPTION_KEY=your-64-character-hex-output

Restart Strapi. From now on all new credentials are encrypted with this key. Do not change this key after adding accounts — existing credentials will become undecryptable.

Advanced configuration ​

All options are optional. The plugin ships with safe defaults.

typescript
// config/plugins.ts
export default () => ({
  'magic-mail': {
    enabled: true,
    config: {
      // Custom encryption key (recommended for production)
      encryptionKey: process.env.MAGIC_MAIL_ENCRYPTION_KEY,

      // Verbose logging — useful during development
      debug: process.env.NODE_ENV === 'development',

      // Global rate-limit settings (individual accounts can override)
      rateLimit: {
        enabled: true,
        window: 3600, // seconds
        maxRequests: 100,
      },

      // Optional: pin a default sender address. Used when the
      // caller does not supply `from`.
      defaultFrom: 'noreply@example.com',
    },
  },
});

Environment variables (optional) ​

bash
# Custom encryption key for credentials at rest
MAGIC_MAIL_ENCRYPTION_KEY=your-32-byte-hex-key

# Enable verbose Magic-Mail logs
DEBUG=magic-mail:*

# Redis connection for shared rate-limit tracking (multi-instance deployments)
REDIS_URL=redis://localhost:6379

Verify installation ​

Check the admin panel sidebar for the Magic-Mail entry. Under Email Accounts you should see the accounts list (empty initially).

You can also verify from code:

js
// Anywhere in your Strapi project
const emailRouter = strapi.plugin('magic-mail').service('email-router');
console.log(typeof emailRouter.send); // 'function'

Installing alongside other plugins ​

Magic-Mail works seamlessly with:

Install them together:

bash
npm install strapi-plugin-magic-mail strapi-plugin-magic-link-v5
typescript
export default () => ({
  'magic-mail': { enabled: true },
  'magic-link': { enabled: true },
});

Troubleshooting install errors ​

If the plugin does not appear in the sidebar after npm run develop:

bash
rm -rf .cache node_modules/.cache dist
npm run build
npm run develop

For peer-dependency warnings:

bash
npm install --legacy-peer-deps

See Troubleshooting for more.

Next: Configure email providers →