Blocks

Manage reusable HTML content blocks that can be embedded in emails using the {{ block.name }} template syntax.

GET/api/v1/blocks

Get all blocks for the authenticated client. Cursor-paginated (per_page default 25, max 100; cursor for next/previous page).

Response Fields

idinteger

The block ID.

uuidstring

The block UUID.

namestring

The block name (lowercase with underscores).

html_contentstring

The HTML content of the block.

created_atstring

ISO 8601 creation timestamp.

updated_atstring

ISO 8601 last update timestamp.

metaobject

Cursor pagination metadata (path, per_page, next_cursor, prev_cursor).

Request

curl -X GET \
  "https://byomailer.com/api/v1/blocks" \
  -H "Authorization: Bearer {your-api-token}" \
  -H "Accept: application/json"

Response

200

{
  "data": [
    {
      "id": 1,
      "uuid": "block-uuid-1",
      "name": "footer_links",
      "html_content": "<div><a href=\"https://example.com\">Home</a></div>",
      "created_at": "2024-01-15T10:30:00.000000Z",
      "updated_at": "2024-01-15T10:30:00.000000Z"
    },
    {
      "id": 2,
      "uuid": "block-uuid-2",
      "name": "welcome_header",
      "html_content": "<h1>Welcome!</h1>",
      "created_at": "2024-01-14T09:00:00.000000Z",
      "updated_at": "2024-01-14T09:00:00.000000Z"
    }
  ],
  "meta": {
    "path": "https://byomailer.com/api/v1/blocks",
    "per_page": 25,
    "next_cursor": null,
    "prev_cursor": null
  }
}

GET/api/v1/blocks/{blockId}

Get a single block by ID.

Path Parameters

blockIdinteger

required

The ID of the block to retrieve.

Response Fields

idinteger

The block ID.

uuidstring

The block UUID.

namestring

The block name.

html_contentstring

The HTML content of the block.

created_atstring

ISO 8601 creation timestamp.

updated_atstring

ISO 8601 last update timestamp.

Request

curl -X GET \
  "https://byomailer.com/api/v1/blocks/{blockId}" \
  -H "Authorization: Bearer {your-api-token}" \
  -H "Accept: application/json"

Response

200

{
  "data": {
    "id": 1,
    "uuid": "block-uuid-1",
    "name": "footer_links",
    "html_content": "<div><a href=\"https://example.com\">Home</a></div>",
    "created_at": "2024-01-15T10:30:00.000000Z",
    "updated_at": "2024-01-15T10:30:00.000000Z"
  }
}

POST/api/v1/blocks

Create a new reusable HTML content block. The html_content is validated for safe HTML — script tags, iframes, event handlers, and other unsafe elements are rejected.

Body Parameters

namestring

required

The block name. Must be lowercase letters, numbers, and underscores only. Unique per account.

html_contentstring

required

The HTML content of the block. Must be valid, safe HTML.

Response Fields

idinteger

The block ID.

uuidstring

The block UUID.

namestring

The block name.

html_contentstring

The HTML content of the block.

created_atstring

ISO 8601 creation timestamp.

updated_atstring

ISO 8601 last update timestamp.

Request

curl -X POST \
  "https://byomailer.com/api/v1/blocks" \
  -H "Authorization: Bearer {your-api-token}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "footer_links",
  "html_content": "<div><a href=\"https://example.com\">Home</a></div>"
}'

Response

201

{
  "data": {
    "id": 3,
    "uuid": "block-uuid-3",
    "name": "footer_links",
    "html_content": "<div><a href=\"https://example.com\">Home</a></div>",
    "created_at": "2024-01-16T11:00:00.000000Z",
    "updated_at": "2024-01-16T11:00:00.000000Z"
  }
}

PATCH/api/v1/blocks/{blockId}

Update an existing block. The html_content is validated for safe HTML.

Path Parameters

blockIdinteger

required

The ID of the block to update.

Body Parameters

namestring

required

The new block name. Must be lowercase letters, numbers, and underscores only. Unique per account.

html_contentstring

required

The new HTML content. Must be valid, safe HTML.

Response Fields

idinteger

The block ID.

uuidstring

The block UUID.

namestring

The updated block name.

html_contentstring

The updated HTML content.

created_atstring

ISO 8601 creation timestamp.

updated_atstring

ISO 8601 last update timestamp.

Request

curl -X PATCH \
  "https://byomailer.com/api/v1/blocks/{blockId}" \
  -H "Authorization: Bearer {your-api-token}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "updated_footer",
  "html_content": "<div><a href=\"https://example.com\">Updated Home</a></div>"
}'

Response

200

{
  "data": {
    "id": 3,
    "uuid": "block-uuid-3",
    "name": "updated_footer",
    "html_content": "<div><a href=\"https://example.com\">Updated Home</a></div>",
    "created_at": "2024-01-16T11:00:00.000000Z",
    "updated_at": "2024-01-16T12:00:00.000000Z"
  }
}

DELETE/api/v1/blocks/{blockId}

Delete a block.

Path Parameters

blockIdinteger

required

The ID of the block to delete.

Request

curl -X DELETE \
  "https://byomailer.com/api/v1/blocks/{blockId}" \
  -H "Authorization: Bearer {your-api-token}" \
  -H "Accept: application/json"

Response

204

No content