chore(docs): new guide for sending email via http api

[ndom91]

NOTE:

• It's a good idea to open an issue first to discuss potential changes.
• Please make sure that you are NOT opening a PR to fix a potential security vulnerability. Instead, please follow the Security guidelines to disclose the issue to us confidentially.

☕️ Reasoning

• Added new guide (/guides/providers/email-http) for sending Emails (Magic Link verification) via HTTP email APIs, like those from cloud email service providers like SendGrid, Postmark, AWS SES, etc.
• Q: Should I open another PR for "back-porting" and merging this guide into v4 docs?

🧢 Checklist

• Documentation
• Tests
• Ready to be merged

🎫 Affected issues

Please scout and link issues that might be solved by this PR.

Fixes: INSERT_ISSUE_LINK_HERE

📌 Resources

• Security guidelines
• Contributing guidelines
• Code of conduct
• Contributing to Open Source

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated
auth-docs	❌ Failed (Inspect)			Mar 5, 2023 at 3:32PM (UTC)

1 Ignored Deployment

Name	Status	Preview	Comments	Updated
next-auth-docs	⬜️ Ignored (Inspect)			Mar 5, 2023 at 3:32PM (UTC)

[balazsorban44]

Suggested change

- Install `nodemailer` as a dependency. The email provider also requires the use of a database adapter for Auth.js.

the point of this guide is to not need nodemailer

[ndom91]

Right, but you need it for the Email provider atm. It'll complain if you don't install it. I guess we can modify that in core.

[ndom91]

I removed the text actually since its a default dependency in the example-repo as well.

[balazsorban44]

It'll complain if you don't install it

Right, because we have the import at the top of the module... 🤦 Then I would not use EmailProvider at all. The whole point of this tutorial is to get rid of nodemailer, it feels weird to recommend installing it, and it's also quite big.

[balazsorban44]

General feedback:

• Let's use NextAuth.js if we are referencing next-auth
• Let's use "we" over "I"
• Let's copy the default text style

  next-auth/packages/core/src/providers/email.ts

  Lines 175 to 177 in 533320e

  	function text({ url, host }: { url: string; host: string }) {
  	return `Sign in to ${host}\n${url}\n\n`
  	}

• Should we add the HTML version of the e-mail too?

  next-auth/packages/core/src/providers/email.ts

  Line 122 in 533320e

  function html(params: { url: string; host: string; theme: Theme }) {

Essentially, an HTTP-based E-mail provider should only need a single sendVerificationRequest method, and no other config. I'll leave it up to you, but we might not even need the EmailProvider import, just do:

...
{
  type: "email",
  id: "sendgrid",
  async sendVerificationRequest() {
    ...
  }
}
...

Should mention that to sign the user in, you could call signIn("sendgrid", { email: "user@example.com" }) in the client. (Or id is email if you decide to keep the EmailProvider wrapper)

[ndom91]

General feedback:

• Let's use NextAuth.js if we are referencing next-auth
• Let's use "we" over "I"
• Let's copy the default text style

  next-auth/packages/core/src/providers/email.ts

  Lines 175 to 177 in 533320e

  	function text({ url, host }: { url: string; host: string }) {
  	return `Sign in to ${host}\n${url}\n\n`
  	}

• Should we add the HTML version of the e-mail too?

  next-auth/packages/core/src/providers/email.ts

  Line 122 in 533320e

  function html(params: { url: string; host: string; theme: Theme }) {

Essentially, an HTTP-based E-mail provider should only need a single sendVerificationRequest method, and no other config. I'll leave it up to you, but we might not even need the EmailProvider import, just do:

...
{
  type: "email",
  id: "sendgrid",
  async sendVerificationRequest() {
    ...
  }
}
...

Should mention that to sign the user in, you could call signIn("sendgrid", { email: "user@example.com" }) in the client. (Or id is email if you decide to keep the EmailProvider wrapper)

Yeah so first of all, good suggestions all the way through, committed almost all of them.

Wasn't sure about the NextAuth.js / Auth.js thing since this is giong in the main docs atm but the package is still next-auth (imagine how confusing it is for our users atm 😅).

I'll go over it again with the text style updates and add the HTML email as well. I actually implemented this in that briefkasten app of mine while I wrote this yesterday to make sure it worked and since I was still sending emails via my own gmail account SMTP there previously haha. So I used our html wrapper, works just fine. Can copy that over to the guide too 👍

Regarding the EmailProvider wrapper or just a custom provider like that ^^, wouldn't we be missing out on the verification request db creation? Or does that happen in core if the provider uses a sendVerificationRequest method? I think we should keep it more straight forward and just use the EmailProvider (without the nodemailer hard requirement I mentioned above), what do you think? Otherwise, yeah its just the EmailProvider({ sendVerificationRequest }) 👍

[ndom91]

Changed to we and mentioend our html function adn the text/plain/text/html body type thing 👍

[balazsorban44]

EmailProvider is not necessary, the way we know it's an email provider is through the type: "email" property. 😉 See #6555 (comment)

[ndom91]

EmailProvider is not necessary, the way we know it's an email provider is through the type: "email" property. 😉 See #6555 (comment)

Okay great, will remove it then and do the custom provider route you mentioned to avoid nodemailer as well 👍

[ndom91]

@balazsorban44 alright, should be more or less ready to go 👍

[balazsorban44]

This was not addressed: #6555 (comment)

[ndom91]

This was not addressed: #6555 (comment)

You mean removing the nodemaiker point? That should definitely be gone and I changed it to a custom provider so it doesn't complain anymore