SendGrid Integration

How LeadSync Talks to the SendGrid Marketing API

SendGrid splits its product into transactional (the SMTP and v3/mail/send endpoints) and marketing (lists, contacts, custom fields, segmentation, journeys). LeadSync only talks to the marketing side -- specifically api.sendgrid.com/v3/marketing/ -- so a SendGrid API Key with the Marketing Campaigns -> Full Access permission is what you need to paste into the connection screen.

Every contact push is sent as a PUT /marketing/contacts with a Bearer-token header. PUT is important here: SendGrid treats the email address as the contact identity, so a repeat submission updates the existing contact rather than creating a duplicate. The contact also gets added to whichever list_ids you picked during connection setup, so segments and automations triggered by list membership fire as soon as the lead lands.

Reserved Fields vs Custom Fields in the Mapper

SendGrid distinguishes between reserved fields (the built-in slots like first_name, last_name, phone_number, address_line_1, city, postal_code, country) and custom fields you create per-account. LeadSync calls GET /marketing/field_definitions to load both arrays, so the mapping screen shows every option your SendGrid account actually accepts -- no guessing, no typos.

Internally LeadSync prefixes reserved fields with _rf_ to keep them separate from custom field IDs (which are random hashes generated by SendGrid). When a lead is processed, that prefix is stripped before the value is placed at the top level of the contact payload, while custom field values are nested under custom_fields using SendGrid's field IDs.

Triggering Automations and Segments from a New Lead

The most common SendGrid setup is to point each lead source at a list, then build a Single Send automation or Automation Journey that triggers on list membership. Because LeadSync writes the contact and adds them to the list in the same API call, the welcome email or onboarding sequence fires within seconds of the form submission.

For more advanced workflows, use SendGrid's segmentation on the custom fields LeadSync populates -- for example "ad_source = facebook AND budget = over_5000" to route hot leads into a different journey than tyre-kickers. The custom field values are queryable in segment builder as soon as the contact lands.

Frequently Asked Questions

In SendGrid, go to Settings -> API Keys -> Create API Key. Choose Restricted Access and grant Marketing Campaigns -> Full Access (the only permission LeadSync needs). Copy the key once it is shown -- SendGrid will not show it again -- and paste it into LeadSync when you create the SendGrid connection.

No. LeadSync uses SendGrid's PUT /marketing/contacts endpoint, which upserts on email address. A repeat submission updates the existing contact's custom field values and re-confirms list membership rather than creating a second row. Your contact count stays clean.

Reserved fields are SendGrid's built-in slots (first_name, last_name, phone_number, address_line_1, city, state_province_region, postal_code, country). Custom fields are extra columns you create yourself in SendGrid under Marketing -> Contacts -> Custom Fields. LeadSync loads both via the field_definitions endpoint so the mapper shows every available destination.

In SendGrid, build an Automation Journey with the trigger set to "When a contact is added to list X". Pick the same list you selected in the LeadSync connection. Because LeadSync adds the contact to that list in the same call that creates them, the journey fires within seconds of the lead arriving.

Yes. Each LeadSync connection is bound to exactly one SendGrid list, so create one connection per list and assign each lead source to the right connection. Common pattern: separate Facebook lead form leads, Google form leads, and LinkedIn form leads into list-specific journeys for cleaner reporting.

SendGrid requires you to comply with anti-spam law in the contact's jurisdiction (CAN-SPAM, GDPR, CASL etc.). The lead form itself is the consent signal -- the contact submitted their email asking to be contacted. Make sure your lead form description and your follow-up emails make the relationship clear, and provide an unsubscribe link (SendGrid adds one automatically to marketing emails).

Map the phone field on your lead form to SendGrid's reserved phone_number field in the LeadSync mapping screen. SendGrid stores it as a string -- it does not validate or normalise the format -- so leads land with whatever the user typed.

New leads start failing with a 401 Unauthorized response and the error is logged on your LeadSync Logs tab. Open the SendGrid connection, paste in a fresh API key, and saved leads resume immediately. Historical leads that hit the failure window appear on the Logs tab so you can replay them manually if needed.

Yes. Send a test lead through your ad form (or use Facebook's lead form preview tool), then check SendGrid -> Marketing -> Contacts and search for the email. You will see every field LeadSync mapped, exactly as the live integration will populate it.

Available Integrations

How It Works

How LeadSync Talks to the SendGrid Marketing API

Reserved Fields vs Custom Fields in the Mapper

Triggering Automations and Segments from a New Lead

Frequently Asked Questions

Start Syncing Leads to SendGrid