Gmail Setup Guide

Connect your Gmail account to FormBlade via SMTP (App Password) or OAuth for one-click authorization.

This guide covers two ways to connect Gmail:

• Gmail SMTP — uses an App Password. Simpler setup, works immediately.
• Gmail OAuth — one-click authorization through Google. More secure (no stored passwords), but requires a Google Cloud project.

Gmail SMTP Setup

SMTP settings

Step 1: Enable 2-Step Verification

App Passwords require 2-Step Verification (2FA) to be enabled on your Google account. If you already have 2FA on, skip to Step 2.

1. Go to myaccount.google.com/security
2. Under "How you sign in to Google", click 2-Step Verification
3. Follow the prompts to set up 2FA using your phone, authenticator app, or security key
4. Complete the verification process

Step 2: Generate an App Password

1. Go to myaccount.google.com/apppasswords
2. If you do not see this page, 2-Step Verification is not enabled — go back to Step 1
3. In the "App name" field, type FormBlade
4. Click Create
5. Google will display a 16-character password (formatted as xxxx xxxx xxxx xxxx)
6. Copy this password. You can paste it with or without spaces — both formats work

Step 3: Configure FormBlade

1. Log in to your FormBlade dashboard
2. Open your form and go to the Settings tab
3. Under Email Provider, select Gmail (SMTP will be pre-selected)
4. The host (smtp.gmail.com), port (587), and encryption (STARTTLS) are pre-filled
5. Enter your Gmail address as the Username
6. Paste the 16-character App Password as the Password
7. Set your From Email to your Gmail address
8. Click Save

Step 4: Send a test email

1. Click Send Test Email
2. Check your inbox for the test notification
3. The email should come from your Gmail address

Gmail SMTP limits

Gmail OAuth Setup

OAuth lets you connect your Gmail account with a single click, without storing any passwords. However, the initial setup requires creating a project in Google Cloud Console.

Overview

The OAuth flow works like this:

1. You create a Google Cloud project and enable the Gmail API
2. You configure an OAuth consent screen and create credentials
3. In FormBlade, you click "Connect Gmail" and authorize access through Google's login screen
4. FormBlade stores a refresh token and uses it to send emails on your behalf

Step 1: Create a Google Cloud project

1. Go to console.cloud.google.com/projectcreate
2. Enter a project name (e.g., "FormBlade Email")
3. Click Create
4. Wait for the project to be created, then make sure it is selected in the project dropdown at the top

Step 2: Enable the Gmail API

1. Go to APIs & Services → Library
2. Search for Gmail API
3. Click on it and click Enable

Step 3: Configure the OAuth consent screen

1. Go to APIs & Services → OAuth consent screen
2. Select External as the user type (unless you have a Google Workspace organization and only want internal users)
3. Click Create
4. Fill in the required fields:
   • App name: FormBlade (or any name)
   • User support email: your email address
   • Developer contact email: your email address
5. Click Save and Continue
6. On the Scopes page, click Add or Remove Scopes
7. Search for gmail.send and check the box next to https://www.googleapis.com/auth/gmail.send
8. Click Update, then Save and Continue
9. On the Test Users page, add your Gmail address as a test user
10. Click Save and Continue

Step 4: Create OAuth credentials

1. Go to APIs & Services → Credentials
2. Click Create Credentials → OAuth client ID
3. Select Web application as the application type
4. Name it "FormBlade"
5. Under Authorized redirect URIs, add the callback URL shown in your FormBlade dashboard's Email Provider settings (typically https://formblade.com/api/auth/gmail/callback)
6. Click Create
7. Copy the Client ID and Client Secret

Step 5: Connect in FormBlade

1. In your form's Settings tab, select Gmail (OAuth) as the email provider
2. Enter the Client ID and Client Secret from Step 4
3. Click Connect Gmail
4. A Google login window will open — sign in with the Gmail account you want to send from
5. Grant FormBlade permission to send emails on your behalf
6. You will be redirected back to FormBlade with the connection confirmed

Publishing for production use

If you want to remove the 7-day token expiration and the 100-user limit, you need to publish your OAuth app and get it verified by Google.

For personal use, testing mode is often sufficient — just re-authorize every 7 days. For a production application serving multiple users, the SMTP App Password method is simpler and does not require Google verification.

Troubleshooting

SMTP: "Username and Password not accepted" error

• You must use an App Password, not your regular Gmail password
• Make sure 2-Step Verification is enabled on your Google account
• If you recently changed your Google account password, all existing App Passwords were invalidated — generate a new one
• Check that the username is your full Gmail address (including @gmail.com)

SMTP: "Too many login attempts" error

• Google temporarily blocks SMTP access after multiple failed login attempts
• Wait 15–30 minutes, then try again with the correct App Password
• Go to myaccount.google.com/notifications and approve any "Suspicious login" alerts

OAuth: "Access blocked: app not verified"

• Your OAuth app is in testing mode and the user trying to authorize is not listed as a test user
• Add the user's email to the test users list in Google Cloud Console → OAuth consent screen → Test users
• Alternatively, when the warning screen appears, click Advanced → Go to [app name] (unsafe) to proceed

OAuth: Token expired after 7 days

• In testing mode, Google expires refresh tokens after 7 days
• Go to your form's Settings in FormBlade and click Reconnect Gmail to re-authorize
• To fix this permanently, publish your OAuth app and go through Google verification

"App Passwords" page not showing up

• App Passwords are only available when 2-Step Verification is enabled
• Google Workspace accounts: your organization administrator may have disabled App Passwords. Contact your IT admin
• Try navigating directly to myaccount.google.com/apppasswords

Gmail sending limits summary

• Daily sending limit via SMTP is unpublished — Google may temporarily block sending if limits are exceeded (rolling 24-hour window)
• Limits are per Gmail account — using the same Gmail for multiple forms shares the same quota
• Google Workspace accounts may have higher limits (up to 2,000/day) but this depends on your admin settings
• Exceeding the limit causes a temporary block (usually 1–24 hours). FormBlade will fall back to the default mail server during this period

Common gotchas

• "Less Secure Apps" is gone — Google permanently removed this option in September 2024. You cannot use your regular Gmail password for SMTP. You must use an App Password (which requires 2FA) or OAuth.
• App Passwords require 2FA first — The App Passwords page will not appear at all unless 2-Step Verification is enabled on your Google account. Enable it at myaccount.google.com/security first.
• Password changes invalidate App Passwords — If you change your Google account password, all existing App Passwords stop working immediately. You will need to generate a new one.
• Gmail Workspace vs. personal accounts — Google Workspace (paid) accounts may have higher sending limits (up to 2,000/day) but your administrator may have disabled App Passwords or SMTP access entirely. Check with your IT admin.
• OAuth testing mode: 7-day token expiry — While your Google Cloud OAuth app is in "Testing" (not published), refresh tokens expire after 7 days. You will need to re-authorize weekly. Publishing and verifying the app removes this limitation but requires a multi-week Google review.
• Sender address must be your Gmail — Gmail SMTP requires the "From" address to match the authenticated Gmail account. You cannot send from a different email address via Gmail SMTP.

Quick reference: where to find things