SendGrid

SendGrid is an add-on for Forms. Once your SendGrid account is connected, every form you edit gains a SendGrid panel in its sidebar where you describe one or more actions. When the form is submitted, each action either sends an email built from one of your SendGrid dynamic templates, or adds the person who submitted to one of your SendGrid marketing lists.

Nothing else about the form changes: validation, messages, redirects, the notification emails Forms sends itself and the Submissions list all behave as they did before.

Connecting your SendGrid account

What the key has to be allowed to do

The plugin asks SendGrid for four different things every time you open the panel, and does two more when a form is submitted:

A key with full access covers all six. If you would rather restrict the key, it needs every one of them — including the two marketing permissions, even on a site that will only ever send email.

Sending an email

The controls

To Name and To Email each accept several values separated by commas, which is how one action reaches more than one person. They are paired up in order, so the first name goes with the first address, the second with the second, and so on. A list of three addresses with only two names leaves the third address without one.

Variables

The Available Variables link above the controls opens a list of everything you can paste into those boxes. Clicking one copies it to your clipboard. There are two kinds:

A field variable is how a confirmation email reaches the person who filled the form in: put your form's email field variable in To Email instead of {{ADMIN_EMAIL}}.

File uploads

A file upload field arrives in the email as a list of links, one per file, under that field's variable. Turn on Attach uploaded files in the action to include readable uploads as real attachments as well. The attachment budget defaults to 5 MiB of original files across one message; files that are missing, unreadable or beyond the remaining budget are omitted rather than turning the whole delivery into an invalid SendGrid request.

Adding someone to a marketing list

What appears in the dropdowns

The Template list reads SendGrid's dynamic templates page by page until there are no more. Legacy templates remain excluded, so a template visible in SendGrid but not here is usually a legacy one.

The Sender list holds your verified senders only. The Select list and Remote field lists come straight from your SendGrid marketing account, so a list or a custom field you add in SendGrid appears here after you reload the form editor.

Switching an action off, and removing one

Each row in the panel shows the action's type — Send Email or Add Contact — a pencil (Edit action) that reopens its modal, and a red X (Remove action) that asks Are you sure you want to remove the item? before acting.

Use the switch on a row to pause or resume that action without losing its settings. The X removes the selected row after confirmation; other actions keep their order and settings. With Conditional Logic installed, a still-enabled action can also run only for submissions that match its conditions.

Deliveries, retries and duplicate limits

Forms writes the entry first and schedules SendGrid afterwards. The visitor does not wait, and a remote failure cannot erase the submission. The Deliveries screen retains SendGrid's explanation. Each accepted action is marked done, so a retry of one failed action does not repeat its successful siblings.

Configuration, authentication and validation failures reported as 400/401/403/404/410/422 are left failed for an administrator to fix. Rate limits, 5xx replies and transport failures are retried after about 1, 5, 30 and 120 minutes, for at most five attempts. Restore the key or action configuration, then retry a permanent failure manually.

Marketing contact writes are upserts and converge on contact state. Transactional mail/send has no provider idempotency key. If SendGrid accepted an email but the site timed out before seeing the response, a later attempt can send that message again; Forms can prevent repeats only after it receives an acceptance response.

For developers

The API key is stored in the xpac option under the sendgrid_api_key key. That option is deliberately not exposed on /wp/v2/settings; it is readable and writable over the settings framework's own wp-react-settings/xpac/read and wp-react-settings/xpac/update routes, both gated on manage_options. The field is a password control in the settings UI; changing its control type does not change the stored option name or value.

Per-form actions live in the form's form_settings post meta on the xpac-form post type, under a sendgrid key, registered on the Forms meta schema and therefore readable and writable over the REST API at /wp-json/wp/v2/xpac-form/<id>. The default is an empty items array:

{
	"sendgrid": {
		"items": [
			{
				"status": true,
				"action": "send",
				"sender": "[email protected]",
				"senderName": "Example",
				"template": "d-…",
				"receiverName": "",
				"receiverEmail": "{{ADMIN_EMAIL}}",
				"replyToName": "",
				"replyToEmail": ""
			},
			{
				"status": true,
				"action": "addContact",
				"list": "…",
				"map": [{ "local": "email", "remote": "email" }],
				"customFields": ["e1_T"]
			}
		]
	}
}

action is send or addContact. sender, senderName, template and the four receiver/reply-to keys are read on the send path; list, map and customFields on the addContact path. An item created in the editor carries the send keys whichever type it is, because the modal starts from one shared set of defaults. customFields holds the subset of map[].remote ids that are custom rather than reserved fields, maintained by the editor as you change a mapping row; the server uses it to split the contact payload between contacts[0] and contacts[0].custom_fields. Items are declared additionalProperties: true, and two keys the runtime depends on are not declared:

• action — read directly on the submit path. An item without it matches neither branch and is dropped.
• condition — the Conditional Logic plugin's own structure. Absent means unconditional.

status is declared, but nothing in the editor ever writes a value other than the true it is created with, because the panel does not enable the shared list's toggle. Forms' shared action-item filter reads it without a fallback, so an item written over REST without status raises a warning, and on a site with Conditional Logic active it raises a TypeError inside the submit request.

Four REST routes back the editor UI, all requiring manage_options:

GET /wp-json/xpac/v1/form/sendgrid/senders
GET /wp-json/xpac/v1/form/sendgrid/templates
GET /wp-json/xpac/v1/form/sendgrid/lists
GET /wp-json/xpac/v1/form/sendgrid/fields

Each route returns a provider message when its lookup fails. All four are requested as soon as the panel mounts, whichever action type you are configuring; once resolved, the actions list stays rendered alongside any connection error.

Sending happens inside Forms' existing public submit route:

POST /wp-json/xpac/v1/form/<form-id>/<instance>/submit

Client talks to https://api.sendgrid.com/v3/ with a bearer token. Its timeout defaults to ten seconds and is filterable through xpac_sendgrid_request_timeout: GET /verified_senders, GET /templates?page_size=20&generations=dynamic, GET /marketing/lists and GET /marketing/field_definitions for the editor; POST /mail/send and PUT /marketing/contacts during queued delivery. Every method checks transport and status errors and preserves the provider explanation and status.

Extension surface

It fires one filter of its own, and that is the whole surface:

apply_filters( 'xpac_sendgrid_email_field_value', $data_value, $type, $key, $submission );

It is reached only from the default branch of the field-type switch that builds the template variables, so checklist, dropdown, radio, confirmation and file fields never pass through it — each of those builds its own display value on its own branch.

The plugin registers no blocks. It attaches to eight PHP hooks: plugins_loaded, admin_notices and rest_api_init from WordPress core for its bootstrap, its missing-Forms notice and its four routes; then xpac_forms_init to initialise, xpac_forms_post_meta_schema and xpac_forms_post_meta_default_values for the shape of its settings, xpac_forms_post_script_dependencies to load its editor panel, and xpac_forms_submit_callbacks for the delivery callback. Forms' dispatcher schedules that callback after the entry logger runs; Deliveries\Runner invokes it off the visitor request and records its classified outcome. Airtable, Brevo, Campaign Monitor, GetResponse, Klaviyo, Mailchimp, TouchBasePro, Zoho and Forms Submission to Post use the same queued contract.

On the editor side the panel is contributed from JavaScript through the xpac-forms-form-panels filter, under panel id and settings key sendgrid. It declares no priority, which is why it sorts below every core Forms panel and why its position relative to other add-ons' panels is not stable. Its action modal can be extended through the xpac-forms-after-settings-modal-content filter, which receives the action's current options with an onChange callback and is passed xpac-sendgrid as the module it is filtering — that is how Conditional Logic adds its condition builder to the modal.