{"id":"pg_sr27_fiz0w_w","property_id":"prp_pfcr5h8cztsp","domain_id":"dom_gkgeprhezjg4wq","root_domain":"smashsend.com","locale":"en","url":"https://smashsend.com/docs/api/broadcasts","url_hash":"76b8eaf8a1627c03bc8f55e959f88c197e73b5b1077b06b38f95aef52a5d7f98","path":"/docs/api/broadcasts","depth":1,"canonical_url":"https://smashsend.com/docs/api/broadcasts","canonical_page_id":null,"page_type":"docs","page_type_guess":"docs","state":"indexed","skip_reason":null,"priority":"1.4","discovered_via":"sitemap","first_seen_at":"2026-08-28T03:07:01.092Z","last_seen_at":"2026-09-27T04:10:47.779Z","http_status":200,"content_hash":"93f64ce8999f1033a89514bdf207a0fe6eb018590099392dd04cc5aaa353b2a4","title":"SMASHSEND Broadcasts API Reference","description":"Create and schedule marketing broadcasts programmatically with raw HTML, merge variables, and automatic compliance.","author":null,"published_at":null,"modified_at":null,"word_count":844,"reading_time_sec":230,"lang_detected":"en","images":[],"links_out":null,"markdown_source":"readability","refresh_interval":"monthly","last_fetched_at":"2026-09-27T04:09:30.257Z","next_refresh_at":"2026-10-27T04:09:30.257Z","runs_count":2,"changes_count":0,"last_changed_at":null,"fail_count":0,"last_error":null,"created_at":"2026-08-28T03:07:01.092Z","updated_at":"2026-08-28T03:07:01.092Z","inlinks":13,"inlinks_body":0,"outlinks":40,"outlinks_external":3,"anchor_terms":[],"template_score":"0.09154929577464788732","cash":"0.160070763947008533","cash_total":"0.6292854667854735652","pagerank":"0.0162500817959562","is_orphan":false,"link_confirmed":true,"discovered_wave":0,"embedded_hash":null,"embedded_at":null,"domain_name":null,"brand_color":null,"domain_rank":null,"spam_score":null,"markdown":"1.  [\n    \n    Home\n    \n    ](https://smashsend.com/)\n\n/\n\n3.  [\n    \n    Docs\n    \n    ](https://smashsend.com/docs)\n\n/\n\n5.  [\n    \n    API Reference\n    \n    ](https://smashsend.com/docs/api)\n\n/\n\n7.  [\n    \n    Broadcasts\n    \n    ](https://smashsend.com/docs/api/broadcasts)\n\nThe Broadcasts API lets you create and schedule marketing broadcasts programmatically — perfect for automating a weekly newsletter from your own pipeline. You send us tested, raw HTML with merge variables; we handle audience resolution, link and open tracking, unsubscribe compliance, and delivery pacing.\n\n**Early access.** The Broadcasts API is currently in early access. It requires the Email API add-on, a verified workspace, and the early-access flag enabled for your workspace — contact support to join.\n\n## Authentication\n\nAll endpoints authenticate with your API key as a Bearer token, exactly like the Emails API. Your workspace is derived from the key — no workspace ID in the URL.\n\n```\nAuthorization: Bearer YOUR_API_KEY\n```\n\n## Create a broadcast\n\nPOST/v1/broadcasts\n\nCreates a draft broadcast from raw HTML. The HTML is stored exactly as you send it; tracking links and required footers are applied when the broadcast is scheduled.\n\n```\ncurl -X POST https://api.smashsend.com/v1/broadcasts \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"Weekly newsletter #42\",\n    \"subject\": \"This week: {{firstName}}, the new roadmap is live\",\n    \"previewText\": \"Fresh updates from the team\",\n    \"fromEmail\": \"news@yourdomain.com\",\n    \"fromName\": \"Dale from Acme\",\n    \"html\": \"<html><body><h1 style=\\\"background:#0b1f3a;color:#fff\\\">Hello {{firstName}}</h1><p>...</p><a href=\\\"{{unsubscribeUrl}}\\\">Unsubscribe</a></body></html>\",\n    \"audience\": { \"all\": true },\n    \"settings\": { \"trackOpens\": true, \"trackClicks\": true }\n  }'\n```\n\nResponse (201): the draft broadcast plus every merge variable we detected in your HTML, subject and preview text.\n\n```\n{\n  \"broadcast\": {\n    \"id\": \"cmp_a1b2c3d4e5f6g7h8i9j0k\",\n    \"name\": \"Weekly newsletter #42\",\n    \"status\": \"DRAFT\",\n    \"subject\": \"This week: {{firstName}}, the new roadmap is live\",\n    \"audience\": { \"all\": true },\n    \"scheduledAt\": null,\n    \"sentAt\": null\n  },\n  \"variables\": {\n    \"detected\": [\"firstName\", \"unsubscribeUrl\"],\n    \"unknown\": []\n  }\n}\n```\n\n## Raw HTML rules\n\n• **Unsubscribe link is mandatory.** If your HTML references {{unsubscribeUrl}} we leave your design untouched. If it doesn't, we append a standard unsubscribe footer — every marketing email must let recipients opt out. One-click unsubscribe headers are always added at the message level.\n\n• **Link tracking.** When trackClicks is on (default), every http(s) link is rewritten through your tracking domain at schedule time. mailto:, tel: and anchor links are never rewritten, and neither is the unsubscribe link.\n\n• **Plain text.** If you don't provide a text version we generate one from your HTML.\n\n• **Size limit.** The HTML body can be up to 500 KB. For best deliverability keep it under 102 KB (Gmail clips larger messages).\n\n## Merge variables\n\nUse {{variableName}} anywhere in the HTML, subject or preview text. Variables resolve per recipient from their contact properties — built-ins like {{firstName}}, {{lastName}} and {{email}}, any custom property by its API slug, plus system URLs: {{unsubscribeUrl}}, {{manageUrl}} (manage preferences) and {{contactId}}.\n\n**Unknown variables are rejected by default.** A variable that doesn't exist as a contact property renders as empty text in the recipient's inbox (\"Hi ,\"), so the create request fails with\n\n`broadcast_unknown_variables` listing the offending names. If you know what you're doing, pass\n\n`\"allowUnknownVariables\": true`.\n\nMissing values (a contact without firstName) always render as empty text — write copy that degrades gracefully, or test with the test endpoint below.\n\n## Send a test\n\nPOST/v1/broadcasts/:broadcastId/test\n\nSends the broadcast to up to 10 workspace members with a \\[TEST\\] subject prefix. Merge variables are rendered so the email looks exactly like the real send. Always test before scheduling.\n\n```\ncurl -X POST https://api.smashsend.com/v1/broadcasts/cmp_a1b2.../test \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{ \"emails\": [\"you@yourdomain.com\"] }'\n```\n\n## Schedule (or send now)\n\nPOST/v1/broadcasts/:broadcastId/schedule\n\nLocks the content, resolves the audience and queues the send. Omit sendAt to send immediately, or pass an ISO timestamp up to 90 days out. deliveryMethod controls pacing: ASAP, PROGRESSIVE, SMART (contact-timezone aware) or WARMUP. If your sending account is new we enforce WARMUP automatically — omit deliveryMethod and we always pick the safest available option.\n\n```\ncurl -X POST https://api.smashsend.com/v1/broadcasts/cmp_a1b2.../schedule \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{ \"sendAt\": \"2026-07-08T15:00:00Z\" }'\n```\n\nScheduled broadcasts can be stopped with POST /v1/broadcasts/:broadcastId/cancel any time before sending starts (the broadcast returns to draft).\n\n## Read broadcasts\n\nGET/v1/broadcasts\n\nLists broadcasts (cursor-paginated, filter with ?status=DRAFT). Fetch one with GET /v1/broadcasts/:broadcastId — poll status to follow the lifecycle: DRAFT → SCHEDULED → IN\\_PROGRESS → COMPLETED.\n\n## Full example: automated weekly newsletter (Python)\n\n```\nimport requests\n\nAPI = \"https://api.smashsend.com\"\nHEADERS = {\"Authorization\": \"Bearer YOUR_API_KEY\"}\n\n# 1. Create the draft from your generated, client-safe HTML\ncreate = requests.post(f\"{API}/v1/broadcasts\", headers=HEADERS, json={\n    \"name\": \"Weekly newsletter\",\n    \"subject\": \"{{firstName}}, this week's update\",\n    \"fromEmail\": \"news@yourdomain.com\",\n    \"fromName\": \"Dale from Acme\",\n    \"html\": open(\"newsletter.html\").read(),\n    \"audience\": {\"all\": True},\n}).json()\n\nbroadcast_id = create[\"broadcast\"][\"id\"]\nassert not create[\"variables\"][\"unknown\"], create[\"variables\"]\n\n# 2. Send yourself a test\nrequests.post(f\"{API}/v1/broadcasts/{broadcast_id}/test\",\n              headers=HEADERS, json={\"emails\": [\"you@yourdomain.com\"]})\n\n# 3. Schedule for tomorrow 9am UTC (after you've checked the test!)\nrequests.post(f\"{API}/v1/broadcasts/{broadcast_id}/schedule\",\n              headers=HEADERS, json={\"sendAt\": \"2026-07-08T09:00:00Z\"})\n```\n\n## Errors\n\n• `broadcast_api_not_enabled` (403) — your workspace isn't in the early-access program yet.  \n• `broadcast_api_addon_required` (402) — enable the Email API add-on in billing settings.  \n• `broadcast_api_workspace_not_verified` (403) — your workspace must be verified before sending.  \n• `broadcast_unknown_variables` (400) — fix the listed variables or pass allowUnknownVariables.  \n• `campaigns/invalid_from_email` (400) — the from address isn't verified; the response lists your allowed emails and domains.  \n• `campaigns/delivery_method_not_available` (400) — usually means WARMUP is required for a new sending account.","storage":{"htmlKey":"stealpage/html/smashsend.com/pg_sr27_fiz0w_w/run_smjznli11yck.html.gz","markdownKey":"stealpage/md/smashsend.com/pg_sr27_fiz0w_w/run_smjznli11yck.md.gz"},"facets":null,"assets":[{"kind":"image","src_url":"https://smashsend.com/og/api_docs.jpg","r2_key":null,"alt":null,"caption":null,"width":null,"height":null,"is_hero":true,"zone":"main"},{"kind":"image","src_url":"https://smashsend.com/_next/static/media/smashsend_dark.da05b6ec.svg","r2_key":null,"alt":"SMASHSEND email marketing - The #1 Email Marketing Tool that turns emails into revenue","caption":null,"width":135,"height":30,"is_hero":false,"zone":"unknown"},{"kind":"image","src_url":"https://smashsend.com/dashboard/integrations/zapier_icon_filled.png","r2_key":null,"alt":"Zapier","caption":null,"width":20,"height":20,"is_hero":false,"zone":"nav"},{"kind":"image","src_url":"https://smashsend.com/dashboard/integrations/mailchimp_icon.png","r2_key":null,"alt":"Mailchimp","caption":null,"width":20,"height":20,"is_hero":false,"zone":"nav"},{"kind":"image","src_url":"https://smashsend.com/dashboard/integrations/webhooks_icon_gradient.png","r2_key":null,"alt":"Webhooks","caption":null,"width":20,"height":20,"is_hero":false,"zone":"nav"},{"kind":"image","src_url":"https://smashsend.com/dashboard/integrations/events.png","r2_key":null,"alt":"Events API","caption":null,"width":20,"height":20,"is_hero":false,"zone":"nav"},{"kind":"image","src_url":"https://smashsend.com/_next/image?url=%2Favatar-profile.png&w=3840&q=75","r2_key":null,"alt":"Jorge Ferreiro","caption":null,"width":null,"height":null,"is_hero":false,"zone":"nav"},{"kind":"image","src_url":"https://smashsend.com/_next/image?q=75&url=%2Favatar-profile.png&w=3840","r2_key":null,"alt":"Jorge Ferreiro","caption":null,"width":null,"height":null,"is_hero":false,"zone":"nav"},{"kind":"image","src_url":"https://smashsend.com/_next/static/media/smashsend_light.be8a3849.svg","r2_key":null,"alt":"SMASHSEND email marketing - The #1 Email Marketing Tool that turns emails into revenue","caption":null,"width":171,"height":38,"is_hero":false,"zone":"footer"},{"kind":"image","src_url":"https://smashsend.com/marketing/legal/gdpr_compliance.png","r2_key":null,"alt":"SOC2","caption":null,"width":null,"height":50,"is_hero":false,"zone":"footer"}],"shots":[{"viewport":"mobile","width":390,"height":844,"r2_key":"stealpage/shots/smashsend.com/pg_sr27_fiz0w_w/run_smjznli11yck-mobile.png","phash":"26f486a4b8b0c482","visual_delta":0,"captured_at":"2026-09-27T04:09:34.150Z"},{"viewport":"desktop","width":1440,"height":900,"r2_key":"stealpage/shots/smashsend.com/pg_sr27_fiz0w_w/run_smjznli11yck-desktop.png","phash":"a6636149686060f0","visual_delta":0,"captured_at":"2026-09-27T04:09:33.914Z"},{"viewport":"mobile","width":390,"height":844,"r2_key":"stealpage/shots/smashsend.com/pg_sr27_fiz0w_w/run_a2iycuxwmzmt-mobile.png","phash":"26f486a4b8b0c482","visual_delta":null,"captured_at":"2026-08-28T03:13:08.357Z"},{"viewport":"desktop","width":1440,"height":900,"r2_key":"stealpage/shots/smashsend.com/pg_sr27_fiz0w_w/run_a2iycuxwmzmt-desktop.png","phash":"a6636149686060f0","visual_delta":null,"captured_at":"2026-08-28T03:13:07.623Z"}],"history":[{"id":"run_smjznli11yck","started_at":"2026-09-27T04:09:30.251Z","http_status":200,"fetcher":"direct","changed":false,"diff":{"added":0,"removed":29,"similarity":null},"word_count":844},{"id":"run_a2iycuxwmzmt","started_at":"2026-08-28T03:13:00.207Z","http_status":200,"fetcher":"direct","changed":false,"diff":null,"word_count":873}],"citedBy":[]}