This article provides steps to configure SendGrid as a custom email provider in Auth0. The solution utilises an Auth0 Action that can be adjusted for different SendGrid data regions, such as the Global or European Union (EU) region, by targeting the corresponding SendGrid API endpoint.

• Actions
• Custom Email Provider
• SendGrid

The built-in Auth0 SendGrid integration targets the global API and does not support SendGrid's EU region endpoints.

Steps to use the Custom Email provider for the SendGrid API are outlined below:

1. Navigate to Branding > Email Provider in the Auth0 Dashboard.
2. Enable the Use my own email provider toggle.
3. Select the Custom Provider option. This will open an inline Action editor.
4. In the editor, add the required dependencies:
   1. Select the Modules icon in the left-hand menu.
   2. Add the axios npm module.
5. Add the SendGrid API Key as a secret:
   1. Select the Key icon in the left-hand menu.
   2. Select Add Secret.
   3. Create a secret with the name SENDGRID_API_KEY and paste the API key as the value.
6. The following code can be used as a starting point. In the code, use the correct API for the required SendGrid region. For more details, refer to SendGrid's official documentation on Mail Send API endpoints. 

   /**
    * Handler to be executed while sending an email notification.
    * @param {Event} event - Details about the user and the email notification.
    * @param {CustomEmailProviderAPI} api - Methods and utilities for custom behavior.
    */
   const axios = require("axios");
    
   exports.onExecuteCustomEmailProvider = async (event, api) => {
     // 1. Retrieve the SendGrid API Key from Action Secrets
     const SENDGRID_API_KEY = event.secrets.SENDGRID_API_KEY;
    
     // 2. Prepare the email data from the Auth0 event object
     const emailData = {
       personalizations: [
         {
           to: [{ email: event.notification.to }],
           subject: event.notification.subject,
         },
       ],
       from: {
         email: event.notification.from,
         // Optional: name: "Desired App Name"
       },
       content: [
         {
           type: "text/html",
           value: event.notification.html,
         },
       ],
     };
    
     try {
       // 3. Send the request to SendGrid
       await axios.post("https://api.eu.sendgrid.com/v3/mail/send", emailData, {
         headers: {
           Authorization: `Bearer ${SENDGRID_API_KEY}`,
           "Content-Type": "application/json"
         },
       });
     } catch (error) {
       // Check for server-side errors (e.g., 500, 503) from SendGrid.
       // These might be temporary, so a retry may be appropriate.
       if (error.response && error.response.status >= 500) {
         return api.notification.retry(`SendGrid server error: ${error.message}`);
       }
       return api.notification.drop(`SendGrid request failed: ${error}`);
     }
   };