Skip to content
Pidgely Docs

API reference · Template builder & AI

Update the organization's builder theme

PATCHhttps://api.pidgely.com/template-builder/theme
View as Markdown

Scale plan. Saves the default theme and, optionally, the brand profile. Import brand with apply: true fills both from your website.

Scale plan (403 plan_required otherwise).

Authorization: Bearer pdg_…. An API key with full_access. A sending_access key gets 401 restricted_api_key.

Body parameters

JSON object.

Name Type Required Description
theme object Yes Global look of a builder e-mail. Colors are hex (#rrggbb).
theme.brand_color string No —
theme.text_color string No —
theme.background_color string No —
theme.content_color string No Background of the content card.
theme.link_color string No —
theme.font string No One of system, inter, helvetica, georgia, verdana, trebuchet.
theme.content_width integer No Between 480 and 800.
theme.radius integer No Between 0 and 32.
theme.logo_url string No —
theme.logo_width integer No —
theme.logo_alt string No —
theme.logo_align string No One of left, center, right.
theme.logo_dark_url string No Logo variant shown in dark mode by clients that support it (Apple Mail, iOS); others keep logo_url.
theme.button_text_color string No Label color of buttons on the brand color; empty picks white or near-black automatically.
theme.web_font string No Google Fonts family loaded where e-mail clients support web fonts; font is the fallback stack.
theme.heading_font string No Heading stack (empty = font). One of system, inter, helvetica, georgia, verdana, trebuchet.
theme.heading_web_font string No Google Fonts family for headings (empty = web_font).
brand object No The organization's identity used by AI assist (sender name, links, footer) and the brand import.
brand.name string No Display name.
brand.website string No —
brand.address string No Postal address shown in footers.
brand.socials object[] No —
brand.socials[].network string Yes One of x, linkedin, instagram, facebook, youtube, github, tiktok, discord, website.
brand.socials[].url string Yes Public https URL that receives the events.
brand.imported_from string No Page the brand was imported from.

Request

This endpoint is in the Node.js SDK; the other SDKs don't cover it yet, so call it over HTTP from them.

Node.js
import { Pidgely } from 'pidgely';

const pidgely = new Pidgely(process.env.PIDGELY_API_KEY);

const { data, error } = await pidgely.templateBuilder.updateTheme({
  theme: {
    brand_color: '#2563eb',
    font: 'inter',
    radius: 8,
    logo_url: 'https://acme.com/logo.png',
  },
  brand: {
    name: 'Acme',
    website: 'https://acme.com/',
  },
});
console.log(data ?? error);
cURL
curl -X PATCH 'https://api.pidgely.com/template-builder/theme' \
  -H "Authorization: Bearer $PIDGELY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "theme": {
    "brand_color": "#2563eb",
    "font": "inter",
    "radius": 8,
    "logo_url": "https://acme.com/logo.png"
  },
  "brand": {
    "name": "Acme",
    "website": "https://acme.com/"
  }
}'

Response

200 OK

JSON
{
  "object": "template_builder",
  "theme": {
    "brand_color": "brand_color",
    "text_color": "text_color",
    "background_color": "background_color",
    "content_color": "content_color",
    "link_color": "link_color",
    "font": "system",
    "content_width": 480,
    "radius": 0,
    "logo_url": "logo_url",
    "logo_width": 1,
    "logo_alt": "logo_alt",
    "logo_align": "left",
    "logo_dark_url": "logo_dark_url",
    "button_text_color": "button_text_color",
    "web_font": "web_font",
    "heading_font": "system",
    "heading_web_font": "heading_web_font"
  },
  "brand": {
    "name": "Example",
    "website": "website",
    "address": "address",
    "socials": [
      {
        "network": "x",
        "url": "https://acme.com/webhooks/pidgely"
      }
    ],
    "imported_from": "imported_from"
  }
}

Response fields

Name Type Required Description
object string Yes Object type. One of builder_theme.
theme object Yes Global look of a builder e-mail. Colors are hex (#rrggbb).
theme.brand_color string No —
theme.text_color string No —
theme.background_color string No —
theme.content_color string No Background of the content card.
theme.link_color string No —
theme.font string No One of system, inter, helvetica, georgia, verdana, trebuchet.
theme.content_width integer No Between 480 and 800.
theme.radius integer No Between 0 and 32.
theme.logo_url string No —
theme.logo_width integer No —
theme.logo_alt string No —
theme.logo_align string No One of left, center, right.
theme.logo_dark_url string No Logo variant shown in dark mode by clients that support it (Apple Mail, iOS); others keep logo_url.
theme.button_text_color string No Label color of buttons on the brand color; empty picks white or near-black automatically.
theme.web_font string No Google Fonts family loaded where e-mail clients support web fonts; font is the fallback stack.
theme.heading_font string No Heading stack (empty = font). One of system, inter, helvetica, georgia, verdana, trebuchet.
theme.heading_web_font string No Google Fonts family for headings (empty = web_font).
brand object Yes The organization's identity used by AI assist (sender name, links, footer) and the brand import.
brand.name string No Display name.
brand.website string No —
brand.address string No Postal address shown in footers.
brand.socials object[] No —
brand.socials[].network string Yes One of x, linkedin, instagram, facebook, youtube, github, tiktok, discord, website.
brand.socials[].url string Yes Public https URL that receives the events.
brand.imported_from string No Page the brand was imported from.

Errors

Errors have the shape {"statusCode", "name", "message"}. See Errors for the full list.

Status Name When
401 missing_api_key, restricted_api_key No Authorization: Bearer header, or a sending_access key called an endpoint that needs full_access.
403 invalid_api_key, validation_error The API key is invalid or revoked, or the request is not allowed for this account (unverified domain, plan limit, paused account).
422 validation_error A field is missing or invalid; message names it.
429 rate_limit_exceeded Too many requests per second. Wait for Retry-After seconds.