@goede/nuxt-mail

✉️ Nuxt Mail

This a full rewrite of nuxt-mail using typescript, @nuxt/module-builder and supports Nuxt >=3.0.0 only.

• 📨 Send emails using useNuxtApp().$mail or the useMail() composable
• ⚙️ Generated types based on configuration for type inference
• 📫 Uses nodemailer from within a server route

[!WARNING] This module does not work for statically generated sites (SSG) as it relies on server routes to communicate with the SMTP server.

Install

$ npx nuxi module add @goede/nuxt-mail

Configuration

Add the module to the modules array in your nuxt.config.ts.

// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    [
      "@goede/nuxt-mail",
      {
        message: {
          to: "[e-mail]",
        },
        smtp: {
          host: "smtp.example.com",
          port: 587,
        },
      },
    ],
  ],
  // or use the top-level option:
  mail: {
    message: {
      to: "[e-mail]",
    },
    smtp: {
      host: "smtp.example.com",
      port: 587,
    },
  },
});

[!WARNING] For security reasons a message configuration is required to set a to, cc or bcc property. This prevents sending out mails to arbitrary recipients from the client-side, only to those preconfigured.

The smtp options are required and directly passed to nodemailer. Refer to their documentation for available options.

Besides setting the recipient fields, you can preconfigure other message fields in the message config to send emails with the common values (such as subject, from, etc.).

Usage

Via composable

<script setup>
  const mail = useMail();

  mail.send({
    from: "John Doe",
    subject: "Incredible",
    text: "This is an incredible test message",
  });
</script>

Via injected variable

<script setup>
  const { $mail } = useNuxtApp();

  $mail.send({
    from: "John Doe",
    subject: "Incredible",
    text: "This is an incredible test message",
  });
</script>

Via Options API

<script lang="ts">
  export default defineNuxtcomponent({
    methods: {
      sendEmail() {
        this.$mail.send({
          from: "John Doe",
          subject: "Incredible",
          text: "This is an incredible test message",
        });
      },
    },
  });
</script>

Multiple message configs

Multiple message configurations can be set by changing the message config into an array.

// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    [
      "@goede/nuxt-mail",
      {
        message: [
          { name: "contact", to: "[e-mail]" },
          { name: "support", to: "[e-mail]" },
        ],
        // ...
      },
    ],
  ],
});

These configurations can be used by passing config property that corresponds with the config name. These names will autocomplete using types generated on startup.

mail.send({
  config: "support",
  from: "John Doe",
  subject: "Incredible",
  text: "This is an incredible test message",
});

For legacy purposes we support passing the config index instead of the config name.

[!NOTE] This will be removed in v2 as the config name is now typesafe.

mail.send({
  config: 1, // Resolves to 'support'
  from: "John Doe",
  subject: "Incredible",
  text: "This is an incredible test message",
});

Setting up popular email services

Gmail

You have to setup an app-specific password to log into the SMTP server. Then, add the following config to your nuxt-mail config. Looks like there are multiple ways to configure Gmail, so it's best to try out the options:

// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    [
      "@goede/nuxt-mail",
      {
        smtp: {
          service: "gmail",
          auth: {
            user: "[e-mail]",
            pass: "<app-specific password>",
          },
        },
      },
    ],
  ],
});

// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    [
      "nuxt-mail",
      {
        smtp: {
          host: "smtp.gmail.com",
          port: 587,
          auth: {
            user: "[e-mail]",
            pass: "<app-specific password>",
          },
        },
      },
    ],
  ],
});

Missing something? Add your service here via a pull request.

Debugging mail errors

You can debug errors using the browser developer tools, if a 500 error is thrown (check out the console output), you can find the error message in the Network tab. For Chrome users, open the Network tab and look for the "send" request. Open it and select the "Response" tab, this should show the error message, in most cases the error is related to authentication with the SMTP server.

Open questions

"Self signed certificate in certificate chain" error

There is an open issue where the above error is thrown, if you know what could be causing this or have a solution for this please join the issue discussion and let us know!

Contribute

Are you missing something or want to contribute? Feel free to file an issue or a pull request! ⚙️

License

MIT License © Bobbie Goede & Sebastian Landwehr