SendGrid

SendGrid is an add-on for Forms. Each form gets a SendGrid panel where you add actions: send an email built from one of your dynamic templates, add the person to a marketing list, or remove them. The form and its own notification emails work as before.

Connect SendGrid

The key stays visible to admins on this screen. If the key is missing a permission, the SendGrid panel shows the error at the top and leaves your saved actions in place.

Add it to a form

Edit the form, open the SendGrid panel in the sidebar and click Add SendGrid action. Pick the Action at the top of the dialog: Send email, Add contact or Remove contact. Senders, templates, lists and fields are kept for 10 minutes; click Refresh from SendGrid to fetch them again.

Send email

• Sender: a verified sender, shown with its name and address. Senders SendGrid hasn't verified, or has locked, are listed but can't be picked. Another address on your domain lets you type a From email and From name on a domain you authenticated in SendGrid.
• Template: one of your dynamic templates. Legacy templates aren't listed.
• Recipient email: starts as {{ADMIN_EMAIL}}. Separate addresses with commas; each one gets its own email. Use a field variable to email the person who submitted.
• Recipient name: one name per address, in the same order.
• Reply-to name and Reply-to email: optional.
• Categories: up to 10, separated by commas, for SendGrid statistics.
• Unsubscribe group: people who unsubscribe from this group stop getting these emails. None by default.
• Attach uploaded files: up to 5 MB in total. The template gets file links either way.
• Test mode: SendGrid checks the email, then drops it. Nobody receives it.

Save stays off until you pick a sender and a template, and every recipient is an email address or a variable.

Available variables lists what you can paste into these boxes; click one to copy it. There are four for the site: {{ADMIN_EMAIL}}, {{NOREPLY_EMAIL}}, {{SITE_TITLE}} and {{REFERRER}} (the page the form was on), plus one per form field. Every one of them also reaches your template under the same name, so {{SITE_TITLE}} or {{your_field_name}} works there too. For checkbox, dropdown and radio fields the variable holds the choice's label, and {{your_field_name_value}} holds its value. If that value is an email address, putting the field's variable in Recipient email routes the email by the visitor's choice. If a spot in your template stays blank, check the name matches the field exactly, including case.

Add contact

• List: the marketing list to add the contact to.
• Field mapping: pair each Form field with a SendGrid field: Email, First Name, City and the other built-in fields, or your custom fields.

Save stays off until you pick a list and a row maps to Email. Add contact creates or updates the contact. It sends no confirmation email and records no consent; where you need consent, add a checkbox and use Forms' conditional logic.

Blank answers are left out, so they don't clear what SendGrid already holds. Date fields get the date as YYYY-MM-DD. A Number field needs a number: any other answer fails the delivery. A file field sends its file links. An answer longer than SendGrid allows is cut to fit, and the delivery notes it.

Remove contact

• How to remove: Remove from list (the contact stays in SendGrid), Delete contact (removes it from your SendGrid account), or Unsubscribe (SendGrid stops emailing the address).
• List: with Remove from list.
• Unsubscribe group: with Unsubscribe. All email by default.
• Email field: the form field that holds the address to remove.

An address SendGrid doesn't have counts as done.

Each row in the panel shows the action and where it sends. Use the switch to turn an action off without deleting it. The XPAC Agent can also connect a form to SendGrid for you.

When a send fails

Sends run in the background a moment after the submission is saved, so the visitor never waits. Each one shows on XPAC → Forms → Deliveries:

SendGrid changes contacts in the background too. After it accepts an Add contact, or a Remove contact that removes from a list or deletes, XPAC checks the result for about two hours. If SendGrid refused the contact, or never finished, the delivery turns back to Failed, with a link to SendGrid's details when it gives one. Delivered on an email means SendGrid accepted it, not that it reached the inbox.

A timeout, a rate limit or a server error is retried on its own after about 1, 5, 30 and 120 minutes, up to five tries. Other failures, such as a missing email answer or text in a Number field, stay Failed until you act. Fix the cause, then click Retry now on the delivery, or Retry all failed. A retry sends with the form's current settings and the API key saved now. Actions that already went through aren't sent again unless you've changed them since. If SendGrid accepted an email but its reply was lost, the retry can send that email a second time.

If 5 deliveries in a row fail on one form, XPAC pauses SendGrid on that form and emails the site admin. A refused contact, a missing email answer and a rate limit don't count toward this. While it's paused, submissions are still saved but show as Failed, and XPAC tries one submission an hour. If that one goes through, sending starts again on its own. To start sooner, fix the cause and click Resume and retry on the Deliveries screen.

For developers