Menu

Expand
Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Send Email Verifications with Authy and Twilio SendGrid

For new development, we encourage you to use the Verify API instead of the Authy API. The Verify API is an evolution of the Authy API with continued support for SMS, voice, and email one-time passcodes, an improved developer experience and new features including:

  • Twilio helper libraries in JavaScript, Java, C#, Python, Ruby, and PHP
  • Access via the Twilio CLI
  • Improved Visibility and Insights
  • Push authentication SDK embeddable in your own application

You are currently viewing the Authy API. The Authy API will continue to be maintained, but any new features and development will be on the Verify API. Check out the FAQ for more information and Verify API Reference to get started.

Here's your checklist for setting up your account to send email verifications with Authy and SendGrid. Detailed instructions for each step are included below.

  1. [SendGrid] Create or log in to your SendGrid account
  2. [SendGrid] Create a SendGrid API Key
  3. [SendGrid] Set up domain authentication
  4. [SendGrid] Create an email template
  5. [Authy] Create an Authy application
  6. [Authy] Create an email integration and connect to your Authy application
  7. [Authy] Create an Authy user
  8. [Authy] Send an email verification code
  9. [Authy] Check an email verification code

The initial configuration in Steps 1-6 only needs to be done once. You can then use your email-configured Authy application to send verification emails through the API.

Set up your SendGrid account

Create a SendGrid account or log in to your existing account. Email verifications use the SendGrid transactional email API.

Create a SendGrid API Key

Next, Create a SendGrid API Key via the API or in the SendGrid dashboard

We strongly recommend generating SendGrid API Keys with limited scopes.

Create an API Key in one of two ways:

Option 1: Create an API Key with the SendGrid API.

Option 2: Create an API Key in the SendGrid UI. For permissions, select "Restricted Access" and choose the following limited scopes:

Minimum Permissions for Verify/Email SendGrid API Keys

Save your SendGrid API Key - you'll need it to set up your verification email integration.

Set up Domain Authentication

Domain authentication allows you to send an email from your company's domain without "via sendgrid.net". Head over to the SendGrid docs to learn about how to set up domain authentication then authenticate your domain in the SendGrid dashboard.

It can take up to 48 hours for the records to verify after you upload them into your DNS host, so you will likely have to come back later to verify.

Create an Email Template

Navigate to the SendGrid dashboard and create a new template. For more information on working with dynamic templates, reference the SendGrid documentation.

Use at least one of the first three variables below to include the verify code in your email template.

Available Variables Description
{{twilio_code}} The 4-10 digit numeric One Time Passcode. OTP only, no descriptive text.
{{twilio_message}} Contains both internationalized descriptive text and OTP. i.e. "Your MyServiceName verification code is: 123456" or "Su codigo de verificacion para MyServiceName es: 123456". Default language is English, override language using the Locale parameter.
{{twilio_message_without_code}} Contains the internationalized descriptive text only. i.e. "Your MyServiceName verification code is" or "Su codigo de verificacion para MyServiceName es".
{{twilio_service_name}} [Optional] the Friendly Name of the Service.

Need template help? Check out SendGrid's free and open source library of transactional email templates for robust and responsive designs: https://sendgrid.com/blog/open-source-transactional-email-templates/

Example SendGrid HTML Template with variables

<html>
  <head>
    <style type="text/css">
      body, p, div {
        font-family: Helvetica, Arial, sans-serif;
        font-size: 14px;
      }
      a {
        text-decoration: none;
      }
    </style>
    <title></title>
  </head>
  <body>
  <center>
    <p>
      Example 1 - just the code (no localization in the message):
    </p>
    <p>
      The verification code is: <strong>{{twilio_code}}</strong>
    </p>
    <p>
      Example 2 - use the code in a clickable link to trigger a verification check:
    </p>
    <p>
      <a href="https://your-company.com/signup/email/verify?token={{twilio_code}}" 
         style="background-color:#ffbe00; color:#000000; display:inline-block; padding:12px 40px 12px 40px; text-align:center; text-decoration:none;" 
         target="_blank">Verify Email Now</a>
    </p>
    <p>
      Example 3 - entire localized message and code:
    </p>
    <p>
      <strong>{{twilio_message}}</strong>
    </p>
    <p><a href="https://sendgrid.com/blog/open-source-transactional-email-templates/">Check out more templates</a></p>
    <span style="font-size: 10px;"><a href=".">Email preferences</a></span>
  </center>
  </body>
</html>

This will produce an email that looks like:

verify email template

We recommend using "email preferences" instead of "unsubscribe" for transactional emails like these. Read more: Should you include an unsubscribe link in your transactional email messages?

Create an Authy email integration

Head to the Email Integration section of the Twilio Authy console and click the red button to create a new integration. Name your integration, this can be changed later. Fill in:

Connect your email integration to your Authy application in one of two ways:

Option 1: From your email integration, check the applications[s] you want to associate with that email integration. A single email integration can be used for multiple services.

select authy application email integration

OR

Option 2: From the settings tab on your Authy application in the Twilio console, select the email integration. Each Authy application can only have one email integration.

Email Integration select from verify service

Send an email verification

Now the exciting part! Send your first email verification with the following code:

        
        
        
        

        Update user email

        Emails will always be sent to the email you provided when you added the user to your Application. If you added the user without providing email and phone number you will need to provide one.

        To update an email you need the following code:

              
              
              
              
              Rate this page:

              Need some help?

              We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.