Blog (Headless CMS) Integration

Last updated: Mar 4, 2026Section: Integrations

Blog (Headless CMS) Integration

Full API reference: https://api.mailoo.app/docs/v1

Use Mailoo as a central headless CMS for your blog: create and manage articles in the dashboard and deliver them via an external API by project. External sites (or your own) can consume the same API.

Overview

The Blog integration works like other Mailoo integrations (e.g. Form): you add a Blog integration to a project. All articles for that blog belong to that integration. The API does not provide access to blog articles without authorization. Read API: list articles and get one by slug; requires X-API-Key with scope blog.external-read; access is keyed by project UID and integration ID.

Capabilities:

  • Create, edit, and delete articles in the Mailoo dashboard (per integration)
  • Publish as draft or published; optional excerpt, image, category, tags
  • Read API (X-API-Key required): list published articles and get one by slug, keyed by project UID and integration ID
  • Article response: id, title, slug, excerpt, content (Markdown, source of truth), htmlContent (HTML generated from content by the API; use for display), status, publishedAt, createdAt, updatedAt, author (id, name, email?, avatar), category (id, slug, name or null), featured, readTimeMinutes, image, tags (array, default []). Pagination includes page, limit, total, totalPages, hasNextPage, hasPrevPage.

Creating a Blog Integration

  1. Go to Dashboard → Projects → [Your Project]
  2. Click Create New Integration
  3. Select Blog (Headless CMS)
  4. Set a name and status (e.g. Active)
  5. After creation, open the integration to see the Articles list and Connection block

Managing Articles

On the integration page you can:

  • Articles table: Title, slug, status, date, and Edit for each article
  • Create article: Opens the new-article form (title, excerpt, content, status, image). Content is entered in Markdown (headings, lists, bold, links, etc.); the API converts it to HTML on save.
  • Edit: Opens the edit form for that article (save as draft, publish, or archive). Same Markdown editor for the default locale and for each translation (locales).

Content format: Article body is stored as content in Markdown. The API generates htmlContent from it. Consumers should use htmlContent for display to get correct structure and typography.

Managing Categories

A Categories block on the same integration page lets you manage blog categories (scoped to this integration). Use categories when creating or editing articles.

  • Add category: Enter name and slug (slug is auto-derived from name if left blank), then Add category
  • Edit: Change name or slug for a category, then Save or Cancel
  • Delete: Click Delete, then confirm with Confirm (or Cancel to keep the category). Articles keep their category link until you change it.

Connection (External API)

The Connection block on the integration page shows the endpoints to use from your site or app. For web applications, the only recommended approach is BFF (API key on the server); direct API calls with X-API-Key are for server-to-server use. For Next.js, see blog-nextjs-example{.interpreted-text role="doc"}.

BFF routes (Next.js, same-origin) --- use env vars MAILOO_BLOG_PROJECT_UID, MAILOO_BLOG_INTEGRATION_ID, MAILOO_BLOG_API, MAILOO_BLOG_API_KEY:

  • List published articles: GET /api/v1/blog Query: page, limit, categoryId, locale, featured (optional). Returns { success, data: [...], pagination } with hasNextPage, hasPrevPage.
  • Get one article by slug: GET /api/v1/blog/slug/{slug} Query: locale (optional). Returns { success, data: article }. Only published articles are returned.
  • List categories: GET /api/v1/blog/categories Returns { success, data: Category[] } (id, slug, name).

Direct API calls --- require X-API-Key header and scope blog.external-read:

  • List: GET {baseUrl}/api/v1/blog/{projectUid}/integrations/{integrationId}
  • Single: GET {baseUrl}/api/v1/blog/{projectUid}/integrations/{integrationId}/slug/{slug} Query: locale (optional).
  • Categories: GET {baseUrl}/api/v1/blog/{projectUid}/integrations/{integrationId}/categories

Base URL is your Mailoo API (e.g. https://api.mailoo.app). projectUid and integrationId are shown in the Connection block. Article image is a full URL (consumers may use it as coverImage). Tags are returned as an array; empty array when none. For full response fields and error codes, see the API docs above.

For a full Next.js example, see blog-nextjs-example{.interpreted-text role="doc"}.

📚