Skip to main content

SendGrid

This page provides steps for configuring SendGrid as an email service provider on your self-hosted Appsmith instance.

Prerequisites​

  • A self-hosted Appsmith instance. See the installation guides to set up your Appsmith instance.
  • A SendGrid account. Sign up on the SendGrid Website if you don't have one.
  • A sender identity on SendGrid. You need this to send emails via SendGrid. See the Adding a Sender guide on the SendGrid official documentation.

Configure SendGrid to use SMTP Relay​

  1. Log into your SendGrid account.

  2. Select Email API > Integration Guide from the left nav bar.

  3. Choose SMTP Relay on Integrate using our Web API or SMTP Relay screen.

  4. Click Choose button.

  5. On How to send email using the SMTP relay screen:

    SendGrid email configuration
    Configure SendGrid as your email service provider

    a. Enter a unique name for My First API Key Name field.

    b. Click the Create Key button. SendGrid generates a new key. Make sure to copy and save it for later use.

  6. The API key generated is also shown in the Password field under the Configure your application section.

  7. Keep the SendGrid configuration screen open and proceed to the Configure SendGrid on Appsmith section.

Configure SendGrid on Appsmith​

On Appsmith, you can configure SendGrid by using one of the following ways:

Admin settings​

Attention

If you have configured email using environment variables for your instance, it takes precedence over the configuration provided through the Admin Settings UI.

Follow these steps to configure SendGrid using Admin Settings:

  1. Log into your Appsmith instance as a superuser.

  2. Go to the Admin Settings screen.

  3. Select Email from the left nav bar.

    Email service provider
    Configure SendGrid as your email service provider

  4. Add the configuration details for SendGrid as follows:

    SMTP host
    Add the SMTP host as smtp.sendgrid.net for SendGrid.

    SMTP port
    Add the SMTP port as 587 for using Transport Layer Security (TLS) protocol and 25 for sending emails without encryption.

    From address
    Add a verified email address to be shown in the From field when users receive an email.

    Reply-to address
    Add a verified email address so users can contact you.

    Enable TLS protected connection
    This option is turned off by default. Toggle it to enable the Transport Layer Security protocol.

    SMTP username
    Add the username as apikey for accessing the SMTP service provider. Note that this is the literal string apikey and not the value of the created API key. The username is only needed when the Transport Layer Security protocol is turned on.

    SMTP password
    Add the API Key you created in Configure SendGrid to use SMTP Relay. The password is only needed when the Transport Layer Security protocol is turned on.

  5. Click the SEND TEST EMAIL button to verify the configuration. A toast message appears at the top of the page, indicating the success or failure of the test. Additionally, a test email is sent to your inbox on successful verification.

  6. Click the SAVE & RESTART button to save the configurations and restart the instance with the updated settings.

  7. Proceed to the Verify SendGrid integration section to complete the configuration on SendGrid.

Environment variables​

Follow these steps to configure SendGrid using environment variables:

  1. Go to your Appsmith instance configuration file, such as the docker.env file for Docker or the values.yaml file for Kubernetes.

  2. Update the values of the environment variables as shown below:

    APPSMITH_MAIL_ENABLED
    Set it to true to enable the email service.

    APPSMITH_MAIL_FROM
    Set it to the verified email of the sender.

    APPSMITH_REPLY_TO
    Set it to the email that should receive replies by default.

    APPSMITH_MAIL_HOST
    Set it to smtp.sendgrid.net for SendGrid.

    APPSMITH_MAIL_PORT
    Set it to 587 for using Transport Layer Security (TLS) protocol and 25 for sending emails without encryption.

    APPSMITH_MAIL_SMTP_TLS_ENABLED
    Set it to true to enable Transport Layer Security.

    APPSMITH_MAIL_SMTP_AUTH
    Set it to true to share the APPSMITH_MAIL_USERNAME and APPSMITH_MAIL_PASSWORD with the SMTP server.

    APPSMITH_MAIL_USERNAME
    Set it to the username as apikey for accessing the SMTP service provider. Note that this is the literal string apikey and not the value of the created API key. The username is only needed when the Transport Layer Security protocol is turned on.

    APPSMITH_MAIL_PASSWORD
    Set it to the API Key you created in Configure SendGrid to use SMTP Relay. This is only needed when the Transport Layer Security protocol is turned on.

  3. Save the changes and restart the Appsmith instance.

  4. Proceed to the Verify SendGrid integration section to complete the configuration on SendGrid.

Verify SendGrid integration​

Follow these steps to verify your SendGrid integration:

  1. After triggering a test email, return to the SendGrid screen Integrate using our Web API or SMTP Relay.

    SendGrid email configuration
    Configure SendGrid as your email service provider

  2. Check I've updated my settings checkbox, and click the Next: Verify Integration button.

  3. Click the Verify Integration button on the next screen and wait for SendGrid to verify the test email.

  4. A screen with the message It worked! is displayed on successful verification.

    SendGrid integration success message
    SendGrid integration success message

Troubleshooting​

You may encounter some common errors after configuring SendGrid, such as:

If you continue to face issues, contact the support team using the chat widget at the bottom right of this page.

See also​

Invite Users