PAYLOAD CMS

Connect Payload with mr.timmy.

Install the small Payload plugin, create a connector key and add the URL plus key in timmy.

For developers

Payload is code-first. Install the connector as an npm package, enable it in the Payload config, deploy, then create a key in the Payload admin.

Title, body, SEO fields, featured image, inline images, categories and tags are mapped. If your collection uses different field names, only the snippet mapping needs to change.

For agents: inspect the Payload collection first, then adjust the field names in the snippet. The timmy connection itself only needs an API URL and API key.

Back to integrations

1. Install package

pnpm add @mrtimmy/payload-connector

2. Enable plugin

import { buildConfig } from "payload"
import { mrTimmyPayloadConnector } from "@mrtimmy/payload-connector"

export default buildConfig({
  plugins: [
    mrTimmyPayloadConnector({
      postsCollection: "posts",
      media: {
        collection: "media",
      },
      fields: {
        title: "title",
        content: "content",
        excerpt: "excerpt",
        slug: "slug",
        metaTitle: "meta.title",
        metaDescription: "meta.description",
        focusKeyword: "focusKeyword",
        featuredImageUrl: "featuredImage",
        categories: "categories",
        tags: "tags",
      },
      taxonomies: {
        categories: {
          collection: "categories",
          matchFields: ["slug", "title"],
        },
        tags: {
          collection: "tags",
          matchFields: ["slug", "title"],
        },
      },
    }),
  ],
})

For Payload in Next.js, also add it to next.config.js as an external server package.

const nextConfig = {
  serverExternalPackages: ["@mrtimmy/payload-connector"],
}

export default nextConfig

3. Check mapping

timmy sends these values. If your Payload fields use different names, only the paths under fields need to change.

timmy sends

Titletitle
Post bodycontent
Excerptexcerpt
SEO titlemetaTitle
SEO descriptionmetaDescription
URL slugslug
Focus keywordfocusKeyword
Featured imagefeaturedImage
Inline imagesMarkdown images in content
Categories and tagscategories, tags

Payload expects

titleText field for the post title
contentRich text or text field for the main body
slugURL field for the blog path
meta.titleSEO title or mapped SEO field
meta.descriptionSEO description or mapped SEO field
focusKeywordFocus keyword, if the site stores one
featuredImageUpload field for the media collection
categoriesoptional: relation or field for categories
tagsoptional: relation or field for tags

4. Add it in timmy

In the Payload admin under mr.timmy → Connector Keys create a key.

API URL:https://example.com/api/mrtimmy/create-post

API key:timmy_xxx

Common errors

401: The API key is wrong or disabled.
404: The plugin is not installed, not deployed or the path is wrong.
500: Payload server error. The response names the failing step: rich text conversion, taxonomy mapping, media upload or Payload create.