API reference · Template builder & AI

Rewrite a block with AI

POSThttps://api.pidgely.com/template-builder/ai/rewrite

Scale plan. Improves, shortens, lengthens, fixes or changes the tone of one block. The block keeps its id, type, style and links; only the words change.

The block keeps its id, type, style and links; only words and emphasis change. Scale plan.

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
`block`	object	Yes	One row of the e-mail. Fields per type: heading (level, text), text and quote (runs), button (label, href, full_width), image (src, alt, href, width), divider (thickness), spacer (height), columns (2-3 columns of blocks, not nested), list (ordered, items), code (text), social (links), footer (runs, unsubscribe, unsubscribe_label, unsubscribe_url).
`block.id`	string	No	Unique id (UUID).
`block.type`	string	Yes	One of `heading`, `text`, `button`, `image`, `divider`, `spacer`, `columns`, `list`, `quote`, `code`, `social`, `footer`.
`block.style`	object	No	—
`block.style.align`	string	No	One of `left`, `center`, `right`.
`block.style.color`	string	No	—
`block.style.background`	string	No	—
`block.style.font_size`	integer	No	Between 10 and 64.
`block.style.padding`	object	No	—
`block.style.padding.top`	integer	Yes	—
`block.style.padding.right`	integer	Yes	—
`block.style.padding.bottom`	integer	Yes	—
`block.style.padding.left`	integer	Yes	—
`block.level`	integer	No	One of `1`, `2`, `3`.
`block.text`	string	No	—
`block.runs`	object[]	No	—
`block.runs[].text`	string	Yes	—
`block.runs[].bold`	boolean	No	—
`block.runs[].italic`	boolean	No	—
`block.runs[].href`	string	No	—
`block.label`	string	No	—
`block.href`	string	No	—
`block.full_width`	boolean	No	—
`block.src`	string	No	—
`block.alt`	string	No	—
`block.width`	integer	No	—
`block.height`	integer	No	—
`block.thickness`	integer	No	—
`block.columns`	object[]	No	—
`block.columns[].blocks`	object[]	Yes	—
`block.columns[].blocks[].id`	string	No	Unique id (UUID).
`block.columns[].blocks[].type`	string	Yes	One of `heading`, `text`, `button`, `image`, `divider`, `spacer`, `columns`, `list`, `quote`, `code`, `social`, `footer`.
`block.columns[].blocks[].style`	object	No	—
`block.columns[].blocks[].level`	integer	No	One of `1`, `2`, `3`.
`block.columns[].blocks[].text`	string	No	—
`block.columns[].blocks[].runs`	object[]	No	—
`block.columns[].blocks[].label`	string	No	—
`block.columns[].blocks[].href`	string	No	—
`block.columns[].blocks[].full_width`	boolean	No	—
`block.columns[].blocks[].src`	string	No	—
`block.columns[].blocks[].alt`	string	No	—
`block.columns[].blocks[].width`	integer	No	—
`block.columns[].blocks[].height`	integer	No	—
`block.columns[].blocks[].thickness`	integer	No	—
`block.columns[].blocks[].columns`	object[]	No	—
`block.columns[].blocks[].ordered`	boolean	No	—
`block.columns[].blocks[].items`	object[][]	No	—
`block.columns[].blocks[].links`	object[]	No	—
`block.columns[].blocks[].unsubscribe`	boolean	No	—
`block.columns[].blocks[].unsubscribe_label`	string	No	—
`block.columns[].blocks[].unsubscribe_url`	string	No	Default `{{{PIDGELY_UNSUBSCRIBE_URL}}}` (filled per recipient by broadcasts; pass it as a variable on API sends).
`block.ordered`	boolean	No	—
`block.items`	object[][]	No	—
`block.links`	object[]	No	—
`block.links[].network`	string	Yes	One of `x`, `linkedin`, `instagram`, `facebook`, `youtube`, `github`, `tiktok`, `discord`, `website`.
`block.links[].url`	string	Yes	Public `https` URL that receives the events.
`block.unsubscribe`	boolean	No	—
`block.unsubscribe_label`	string	No	—
`block.unsubscribe_url`	string	No	Default `{{{PIDGELY_UNSUBSCRIBE_URL}}}` (filled per recipient by broadcasts; pass it as a variable on API sends).
`action`	string	Yes	One of `improve`, `shorten`, `lengthen`, `fix`, `tone`.
`tone`	string	No	One of `friendly`, `professional`, `playful`, `persuasive`, `formal`, `casual`, `empathetic`, `urgent`.
`language`	string	No	—
`variables`	string[]	No	Typed variables (up to 50). `FIRST_NAME`, `LAST_NAME`, `EMAIL` and `UNSUBSCRIBE_URL` are reserved.
`template_id`	string	No	UUID.

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.ai.rewrite({
  block: {
    type: 'text',
    runs: [
      {
        text: 'Thanks for signing up. We are glad you are here.',
      },
    ],
  },
  action: 'tone',
  tone: 'friendly',
});
console.log(data ?? error);

cURL

curl -X POST 'https://api.pidgely.com/template-builder/ai/rewrite' \
  -H "Authorization: Bearer $PIDGELY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "block": {
    "type": "text",
    "runs": [
      {
        "text": "Thanks for signing up. We are glad you are here."
      }
    ]
  },
  "action": "tone",
  "tone": "friendly"
}'

Response

200 OK

JSON

{
  "object": "template_builder",
  "block": {
    "id": "0199d8a2-6f3c-7c51-9e2a-3b1f0c6d4e21",
    "type": "heading",
    "style": {
      "align": "left",
      "color": "color",
      "background": "background",
      "font_size": 10,
      "padding": {
        "top": 1,
        "right": 1,
        "bottom": 1,
        "left": 1
      }
    },
    "level": 1,
    "text": "Hello!",
    "runs": [
      {
        "text": "Hello!",
        "bold": false,
        "italic": false,
        "href": "href"
      }
    ],
    "label": "label",
    "href": "href",
    "full_width": false,
    "src": "src",
    "alt": "alt",
    "width": 1,
    "height": 1,
    "thickness": 1,
    "columns": [
      {
        "blocks": [
          {
            "id": "0199d8a2-6f3c-7c51-9e2a-3b1f0c6d4e21",
            "type": "heading",
            "style": {
              "align": null,
              "color": null,
              "background": null,
              "font_size": null,
              "padding": null
            },
            "level": 1,
            "text": "Hello!",
            "runs": [
              null
            ],
            "label": "label",
            "href": "href",
            "full_width": false,
            "src": "src",
            "alt": "alt",
            "width": 1,
            "height": 1,
            "thickness": 1,
            "columns": [
              null
            ],
            "ordered": false,
            "items": [
              null
            ],
            "links": [
              null
            ],
            "unsubscribe": false,
            "unsubscribe_label": "unsubscribe_label",
            "unsubscribe_url": "unsubscribe_url"
          }
        ]
      }
    ],
    "ordered": false,
    "items": [
      [
        {
          "text": "Hello!",
          "bold": false,
          "italic": false,
          "href": "href"
        }
      ]
    ],
    "links": [
      {
        "network": "x",
        "url": "https://acme.com/webhooks/pidgely"
      }
    ],
    "unsubscribe": false,
    "unsubscribe_label": "unsubscribe_label",
    "unsubscribe_url": "unsubscribe_url"
  }
}

Response fields

Name	Type	Required	Description
`object`	string	Yes	Object type. One of `template_ai_block`.
`block`	object	Yes	One row of the e-mail. Fields per type: heading (level, text), text and quote (runs), button (label, href, full_width), image (src, alt, href, width), divider (thickness), spacer (height), columns (2-3 columns of blocks, not nested), list (ordered, items), code (text), social (links), footer (runs, unsubscribe, unsubscribe_label, unsubscribe_url).
`block.id`	string	No	Unique id (UUID).
`block.type`	string	Yes	One of `heading`, `text`, `button`, `image`, `divider`, `spacer`, `columns`, `list`, `quote`, `code`, `social`, `footer`.
`block.style`	object	No	—
`block.style.align`	string	No	One of `left`, `center`, `right`.
`block.style.color`	string	No	—
`block.style.background`	string	No	—
`block.style.font_size`	integer	No	Between 10 and 64.
`block.style.padding`	object	No	—
`block.style.padding.top`	integer	Yes	—
`block.style.padding.right`	integer	Yes	—
`block.style.padding.bottom`	integer	Yes	—
`block.style.padding.left`	integer	Yes	—
`block.level`	integer	No	One of `1`, `2`, `3`.
`block.text`	string	No	—
`block.runs`	object[]	No	—
`block.runs[].text`	string	Yes	—
`block.runs[].bold`	boolean	No	—
`block.runs[].italic`	boolean	No	—
`block.runs[].href`	string	No	—
`block.label`	string	No	—
`block.href`	string	No	—
`block.full_width`	boolean	No	—
`block.src`	string	No	—
`block.alt`	string	No	—
`block.width`	integer	No	—
`block.height`	integer	No	—
`block.thickness`	integer	No	—
`block.columns`	object[]	No	—
`block.columns[].blocks`	object[]	Yes	—
`block.columns[].blocks[].id`	string	No	Unique id (UUID).
`block.columns[].blocks[].type`	string	Yes	One of `heading`, `text`, `button`, `image`, `divider`, `spacer`, `columns`, `list`, `quote`, `code`, `social`, `footer`.
`block.columns[].blocks[].style`	object	No	—
`block.columns[].blocks[].level`	integer	No	One of `1`, `2`, `3`.
`block.columns[].blocks[].text`	string	No	—
`block.columns[].blocks[].runs`	object[]	No	—
`block.columns[].blocks[].label`	string	No	—
`block.columns[].blocks[].href`	string	No	—
`block.columns[].blocks[].full_width`	boolean	No	—
`block.columns[].blocks[].src`	string	No	—
`block.columns[].blocks[].alt`	string	No	—
`block.columns[].blocks[].width`	integer	No	—
`block.columns[].blocks[].height`	integer	No	—
`block.columns[].blocks[].thickness`	integer	No	—
`block.columns[].blocks[].columns`	object[]	No	—
`block.columns[].blocks[].ordered`	boolean	No	—
`block.columns[].blocks[].items`	object[][]	No	—
`block.columns[].blocks[].links`	object[]	No	—
`block.columns[].blocks[].unsubscribe`	boolean	No	—
`block.columns[].blocks[].unsubscribe_label`	string	No	—
`block.columns[].blocks[].unsubscribe_url`	string	No	Default `{{{PIDGELY_UNSUBSCRIBE_URL}}}` (filled per recipient by broadcasts; pass it as a variable on API sends).
`block.ordered`	boolean	No	—
`block.items`	object[][]	No	—
`block.links`	object[]	No	—
`block.links[].network`	string	Yes	One of `x`, `linkedin`, `instagram`, `facebook`, `youtube`, `github`, `tiktok`, `discord`, `website`.
`block.links[].url`	string	Yes	Public `https` URL that receives the events.
`block.unsubscribe`	boolean	No	—
`block.unsubscribe_label`	string	No	—
`block.unsubscribe_url`	string	No	Default `{{{PIDGELY_UNSUBSCRIBE_URL}}}` (filled per recipient by broadcasts; pass it as a variable on API sends).

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.
502	—	The AI service failed or returned an unusable answer (ai_unavailable, ai_busy, ai_timeout, ai_invalid_output)

Rewrite a block with AI

#Body parameters

#Request

#Response

#Response fields

#Errors

Body parameters

Request

Response

Response fields

Errors