# Emails
## How to use
Your app will not use Bubble’s native “send email” functionality, but instead use our own SendGrid API workflow that generates a nicely-formatted HTML email from the system.
{% hint style="danger" %}
All of the below email flows will only work if you have [set up your SendGrid email ](https://docs.airdev.co/canvas/2.0.0-1/using-the-template/quickstart-guide#step-3-set-up-your-email)AND if you are not on a Hobby plan on the Bubble app (our email setup requires the use of API workflows, a paid Bubble feature).
{% endhint %}
To send a nicely-formatted HTML email:
1. Go to the `Workflows` tab
2. Select `Custom Events`
3. Select `Schedule API workflow`
4. Select `send_email` from the API workflow dropdown
5. Set the scheduled date to `Current date/time`
Fill out the email content in the additional fields.
* **from\_name (required)** - Sender's name to display
* **from\_email (required)** - Sender's email. Note that if your SendGrid account was created after April 6, 2020, you'll need to use a verified sender's email address, or the message will not be sent and you will receive no notification of this (only an error in the Bubble app's server logs). Each SendGrid account can have up to 25 verified senders.
* **reply\_to\_email (optional)** - Sender's alternative email (if reply to email is different from from\_email)
* **to\_emails (required)** - Receiver's email (can be a comma separated list)
* **cc\_emails (optional)** - Carbon copy emails (can be a comma separated list)
* **bcc\_emails (optional)** - Blind carbon copy emails (can be a comma separated list)
* **subject (required)** - Email title / subject
* **body (required)** - Write `
` for a line break (since the parameter is a single line). Dynamic text (e.g., from a multiline input) will handle line breaks automatically.
* Image in the body: `![](https:image’s url’ width=‘518’/>`
* Link in the body: `<a href="link url">Words to be hyperlinked</a>`
* **button\_text (optional)** - By default, there will be no button added to the email. However, if this field isn)
### How does this compare to Bubble's built-in email workflow?
You might be wondering why we would set up a workflow for something that Bubble already does.
However, there are many advantages to setting up your app's emails through Sendgrid's API:
* Send email from your own domain name (e.g. )
* Good for branding, and potentially with spam filters (depending on how many emails you send each month)
* Acess to email metrics or measure success of email marketing
* With our SendGrid integration, you can [check the SendGrid dashboard](https://app.sendgrid.com/) of your account to see these metrics.
* Send attachments with emails
* Customize email's HTML design
* Can make simple changes to the HTML
* For complex customization, you need experience writing HTML for emails - this isn't possible without working with HTML code (outside the scope of this reference)
## Sign up flow - set up email verification
There are currently two sign up flows (modifiable by the App owner from the [General tab in the Admin portal](https://docs.airdev.co/canvas/v/2.0.0/using-the-template/reference/pages/owners-portal-page#admin-portal-overview)):
* 2-step sign up (no email verification)
* 3-step sign up (with email verification)
### 2-step sign up (no email verification)
### 3-step sign up (email verification)
Once the user clicks on the link in the email, they will be redirected to the [verify](https://docs.airdev.co/canvas/2.0.0-1/using-the-template/reference/pages/verify_email) page. If the email verification token is valid, the user will see the following:
If the email verification token is invalid (e.g., the user has already verified his email or the verification link has expired after 24 hours), then the user will see the following:
### Additional UI components you can show in the sign up group
* Social media buttons
* Check the box for *this element is visible on page load* for `Group other buttons (sign up)` and show the social media button group you want to use.
* Add a workflow action that authenticates with the social media site you'd like to use.
* Set up the API keys in the relevant plugin (Facebook, LinkedIn, Gmail, Spotify, etc.). If you don't know how to do this, refer to the Plugins section of our Bubble Development Guide.
* User type toggle
* Check the box for *this element is visible on page load* for `Group User type (sign up)`
* Please remember to change the data source (text) for `Group user type 1` and `Group user type 2`
* Profile picture and other inputs
* Check the box for *this element is visible on page load* for `Group profile pic (sign up)` and `unhide Group additional fields (sign up)`
To add additional inputs to the sign up flow, simply resize `Group Signup DEADSPACE 2/3/or 4` and add your inputs in the space created.
## Email Templates
App admins can manage all email content centrally from the Admin Portal > Settings Tab > Email Templates Tab.
Some basic templates
### Creating a new email template
To add a new email template, you will need to create a new entry in the database (Bubble editor > Data tab > App data tab > Email templates > New entry) and complete the following fields:
* **Email template name (required)** - Name of the email template
* **Unique name id (required)** - Provide a unique name for the template (without spaces)
* **Description (required)** - Brief description about what this template is used for
* **Subject text (required)** - Subject line of the email
* **Body text (required)** - Body of the email
* **Signature content (optional)** - By default this will be `The [app name] team` but you can add a different text in this field to override it
* **List of mail merge terms (optional)** - This includes a list of mail merge terms (list of texts) that can be used in the email template
Terms that are placed within asterisks (e.g., \**FIRSTNAME\**) are mail merge terms that are dynamic.
{% hint style="warning" %}
Email templates will only work if: 1) Your bubble app is not on a hobby plan (you can only schedule API workflows on a paid plan) 2) API workflows have been set up for the template and 3) The email template is enabled
{% endhint %}
### Email API workflows
Each email template is associated with an API workflow in the Emails workflow folder:
* **send\_email\_template**
* You should use this template API workflow whenever you need to create an API workflow for a new email template.
* **send\_email\_html\_email**
* API workflow associated with the *Sample email content email template*
* It is not currently scheduled to fire an email in the app
* **send\_email\_email\_verification**
* API workflow associated with the *Email verification email template*
* This email will only be sent if the App Owner has enabled *Require email verification during sign up* under Settings > General Tab
* **send\_email\_welcome\_email**
* API workflow associated with the *Welcome email template*
* App Owners can enable this from the Email templates tab
* If enabled, the email will be sent to users after they complete the sign up process
* **send\_email\_reset\_pw**
* API workflow associated with *Reset password email template*
* By default, this email template is always enabled in the app as users should always be able to reset their passwords
* **send\_email\_add\_admin**
* API workflow associated with *New admin email template*
* By default, this email template is always enabled in the app. It is used to notify new admins that they've been added to the app.
**How are mail merge terms used?**
Mail merge terms will not correspond to any object in the database. Instead, each email template will have its own list of terms that are managed through the email template's API workflow and its find\&replaces.
{% hint style="warning" %}
Please note that if a mail merge term in the email template copy (e.g., \*FIRSTNAME\*) has been changed (\*FIRST\*), you will also have to update the mailmerge term in the API workflow to \*FIRST\*.
{% endhint %}
Documentation on which mail merge terms to use are on recorded on your canvas template's notes. Each API Workflow has a different set of mail merge terms available. You can also view a list available mail merge terms for each template in the edit email template popup.
