Skip to content
Piksio Docs

SendGrid

Transactional email. A Piksio image goes into SendGrid as an ordinary image link. The platform fills in each recipient’s values, and Piksio renders their version when the email is opened.

Merge tags

Section titled “Merge tags”

SendGrid writes merge tags like {{first_name}}.

SendGrid doesn’t URL-encode values inside links, so keep personalized fields free of & and # (they can cut the link short). If you build the email in code, use the Code output instead: it encodes every value for you.

Built-in fields

Section titled “Built-in fields”

Piksio maps these to SendGrid’s own fields automatically:

Piksio field SendGrid field
first_name first_name
last_name last_name

Custom fields

Section titled “Custom fields”

Any other field must exist in SendGrid before you send. Create it as a custom field in Marketing → Custom Fields, or pass it in your dynamic template data.

Where to paste

Section titled “Where to paste”

Switch the module to code view and paste the HTML.

Formats offered: HTML, Code, Image URL. The default for SendGrid is HTML.

Example

Section titled “Example”

For a design with first_name and company_name, the HTML looks like this:

<img src="https://app.piksio.com/i/YOUR_IMAGE_ID?first_name={{first_name}}&company_name={{company_name}}" width="600" alt="Your personalized image" style="display:block;max-width:100%;height:auto;border:0" />

Building the email in code? The Code output:

// One Piksio image link per recipient. URLSearchParams encodes each value,
// so names like "Smith & Co" are safe. Empty values show the fallback.
function piksioImageUrl(recipient) {
  const values = {
    first_name: recipient.first_name,
    company_name: recipient.company_name,
  };
  const params = new URLSearchParams();
  for (const [key, value] of Object.entries(values)) {
    if (value !== undefined && value !== null && value !== '') params.set(key, String(value));
  }
  const query = params.toString();
  return `https://app.piksio.com/i/YOUR_IMAGE_ID${query ? '?' + query : ''}`;
}


// Put it in the html you send, or pass the link in your dynamic_template_data.
const imageHtml = `<img src="${piksioImageUrl(recipient).replace(/&/g, '&amp;')}" width="600" alt="Your personalized image" style="display:block;max-width:100%;height:auto;border:0" />`;

Check before you send

Section titled “Check before you send”
  1. In Use in email, use Test the link with sample values, and again with unfilled tags. Both are free.
  2. Preview one real recipient in SendGrid to confirm it fills in the fields.
  3. See Fallbacks and blanks for what a recipient with missing data sees.

Sources

Section titled “Sources”

Checked against SendGrid’s own documentation on 2026-10-07: