Meta Ads Bulk Creator

Meta Ads bulk creator

Turns a YAML brief into a Meta Ads Manager bulk-import file. The template (143 columns) is bundled. The script enforces 2026 limits, validates every field, and emits both an .xlsx for review and the Unicode .txt Meta actually parses.

When to use

• Creating more than ~5 ads at once.
• Testing a creative matrix (multiple headlines / bodies / images).
• Replicating a campaign across audiences or geos.
• The user uploads AdsManagerTemplate_v2.3.xltx, mentions a .xltx file, or asks about Meta's bulk import flow.

Not for: editing one or two ads (use Ads Manager UI), API-based ad creation (this is a file producer, not an API client), creative generation (this consumes images, doesn't make them).

The 5-step workflow

1. Gather a brief from the user (YAML preferred). If they have nothing, ask via AskQuestion: campaign name, objective, daily budget, link, CTA, headlines, bodies, image filenames. Default everything else.
2. Validate with python scripts/build_import.py brief.yml --check. Read the report. Fix errors before proceeding.
3. Build with python scripts/build_import.py brief.yml --out ./output --images ./images. Outputs output.xlsx and output.txt.
4. Have the user review output.xlsx. Spot-check ad names, copy, image filenames, audience.
5. Tell the user to upload output.txt in Ads Manager → Import & Export → Import Ads, attach the images folder when prompted, then publish from drafts. See references/workflow.md for the exact UI steps.

Brief schema (YAML)

Minimal:

account:
  page_id: "1234567890"        # used as Link Object ID

creatives:
  - id: hero_a
    files:
      "4:5":  hero_a_4x5.jpg   # required — used as Image File Name
      "9:16": hero_a_9x16.jpg  # required — checked exists, for Stories/Reels

campaigns:
  - name: "Spring 2026 sale"   # 35 chars max
    objective: "Outcome Sales" # see references/enums.md
    daily_budget: 50.00        # CBO budget (no currency symbol)
    ad_sets:
      - name: "Broad AR 25-54"
        optimization_goal: OFFSITE_CONVERSIONS  # required for Sales (no default)
        creative_matrix:
          link: "https://example.com/spring"
          cta: SHOP_NOW
          titles:  ["Spring sale", "Save big", "Don't miss out"]
          bodies:  ["Limited-time...", "Up to 40% off...", "Today only..."]
          creative_ids: [hero_a]   # references creatives[].id

Full schema with overrides: see examples/matrix_brief.yml and examples/sample_brief.yml.

creative_matrix cross-products into one ad per (title × body × creative_id). Default 3 × 3 × 3 = 27 ads in one ad set. Use ads: (a discrete list) instead when each ad is hand-crafted; the script caps at 5 ads per ad set in that mode.

Hardcoded defaults

When the brief omits a field, the script applies these. Full table in references/best-practices.md.

Hard rules the script enforces

Brief-level errors (block the build):

• Names > 35 chars (campaign, ad set, ad).
• Title > 40 chars; Body > 2,200 chars; Description > 200 chars.
• Currency value with a symbol or > 2 decimal places.
• Date not in MM/DD/YY HH:MM.
• Enum value not in the VALIDATION sheet's allowed list (case-sensitive).
• More than 5 ads per ad set when no creative_matrix is used.
• A creative missing the 4:5 or 9:16 file.
• An Image File Name not present in --images directory (case-sensitive).
• Outcome Sales without an explicit optimization_goal.

Brief-level warnings (don't block):

• Title > 27 chars (mobile Feed truncation).
• Body > 125 chars ("See more" link appears).
• Description > 30 chars (often hidden on mobile).
• Status mismatch (e.g. ACTIVE ad inside PAUSED ad set — won't run).
• Special Ad Category set + narrow targeting in brief — script drops the targeting and warns.

See references/limits.md for the full list and references/columns.md for every column's format and enum.

Script usage

python scripts/build_import.py brief.yml \
    --out ./output \
    --images ./images   # optional but recommended

Flags:

• --check — validate only, do not write files. Use this first.
• --out <dir> — output directory (default ./output).
• --images <dir> — directory with the image files referenced in the brief. The script verifies every Image File Name and every creative's 4:5 + 9:16 files exist with exact case.
• --spec <path> — alternate spec.json path (default scripts/spec.json).

Outputs:

• output/output.xlsx — for human review (143 columns, all cells populated).
• output/output.txt — UTF-16 LE BOM, tab-separated, \r\n line endings. This is the file you upload.

Updating to a newer template

If Meta releases a new AdsManagerTemplate_vX.X.xltx:

1. Replace the file in assets/.
2. Re-run python scripts/extract_columns.py to regenerate scripts/spec.json and references/columns.md.
3. Re-run --check against your existing briefs to surface any newly-required columns or removed enums.

Troubleshooting

• Meta rejects output.txt with a parsing error → confirm encoding is UTF-16 LE with BOM (run file output/output.txt; should print "Unicode text, UTF-16, little-endian"). The script always produces this; if it doesn't, the file was modified.
• "Image File Name not found" → exact case match required. Rename files to lowercase + underscores; avoid spaces.
• output.txt exceeds 2 MB → split the brief into multiple campaigns and run the script per campaign.
• Special Ad Category warnings flooding the output → set special_ad_categories: financial_products_services (or whichever applies) at the campaign level and remove custom audiences / lookalikes from the brief.
• All 27 matrix ads have the same image → the brief listed only one creative_id. To get image rotation, list all 3 creative IDs in creative_ids:.

Reference files

• references/columns.md — all 143 columns: level, format, required state, valid values (auto-generated).
• references/workflow.md — Ads Manager UI steps, file size limits, common rejection reasons.
• references/limits.md — 2026 char/format limits, file encoding details.
• references/enums.md — quick lookup for objectives, optimization goals, CTAs, placements.
• references/creative-matrix.md — matrix expansion rules, naming pattern.
• references/best-practices.md — full table of hardcoded defaults with rationale.

Out of scope

• Direct Marketing API calls. This skill produces a file the user uploads in the UI.
• Generating images, videos, or copy.
• Performance analysis after launch.