Email.com docsOpen the app

Guides

Broadcasts API: the three prefixes at a glance

Generated from the broadcasts contract by tests/docs.test.ts (UPDATE_DOCS=1 rewrites it); do not edit by hand. The request and answer schemas, the Problem codes of each route and the MCP markers render on /api-reference from the platform OpenAPI document; this page is the map. A route that needs an Idempotency-Key header replays its first answer for the same key and body and refuses the same key with another body (409). Every refusal is a Problem Details body: a use case answers its code with reason codes and paths, never a submitted value; a body the request schema refuses answers 400 validation with the path of every issue (a refused map key is named in its path).

/v1/broadcasts

OperationRouteScopesRate classIdempotency-KeySummary
broadcasts.listBroadcastsGET /v1/broadcastsbroadcasts:readreadnoThe tenant's broadcasts, newest first (filter by stream, state and creation window)
broadcasts.createBroadcastPOST /v1/broadcastsbroadcasts:writewriterequiredCreate a draft broadcast on a broadcast-lane or test-lane stream of the tenant (422 validation for any other lane)
broadcasts.getBroadcastGET /v1/broadcasts/{broadcast_id}broadcasts:readreadnoOne broadcast with its approval, workflow execution and timeline
broadcasts.updateBroadcastPATCH /v1/broadcasts/{broadcast_id}broadcasts:writewritenoEdit a draft or approved broadcast (an edit of an approved one returns it to draft, clears the approval and changes the content hash); scheduled and later are 409 conflict
broadcasts.getChecklistGET /v1/broadcasts/{broadcast_id}/checklistbroadcasts:readreadnoThe pre-send checklist (identity, stream, template, unsubscribe, consent, frequency, size, verification) with one sample render measured, never returned
broadcasts.sendTestPOST /v1/broadcasts/{broadcast_id}/testbroadcasts:writewriterequiredSend the rendered broadcast to at most 5 verified member addresses of the tenant (S21) through emails.send
broadcasts.approveBroadcastPOST /v1/broadcasts/{broadcast_id}/approvebroadcasts:approvewritenoApprove a draft (a human act): records the approver and locks the content hash; 409 conflict with the failing steps while the checklist has a blocking step
broadcasts.scheduleBroadcastPOST /v1/broadcasts/{broadcast_id}/schedulebroadcasts:writewriterequiredSchedule an approved broadcast now or up to 30 days ahead (the bulk start, S8): the content hash must match the approval, at most 3 scheduled or running broadcasts per tenant; agents need a broadcast.bulk_start grant
broadcasts.cancelBroadcastPOST /v1/broadcasts/{broadcast_id}/cancelbroadcasts:writewritenoCancel a scheduled or running broadcast (remaining batches are skipped; messages emails already accepted are not recalled); completed is 409 conflict
broadcasts.getReportGET /v1/broadcasts/{broadcast_id}/reportbroadcasts:readreadnoCampaign counters from the batch responses and the consumed email events, with batch progress
broadcasts.listRecipientsGET /v1/broadcasts/{broadcast_id}/recipientsbroadcasts:readreadnoRecipients of a broadcast as contact ids and hashes (never an address, D8); filter by state
broadcasts.getStreamPolicyGET /v1/broadcasts/streams/{stream_id}/policybroadcasts:readreadnoThe campaign policy of a stream (defaults when none was saved) with the platform stream snapshot
broadcasts.updateStreamPolicyPATCH /v1/broadcasts/streams/{stream_id}/policybroadcasts:writewritenoChange the campaign policy of a stream of the tenant (stream.policy_changed.v1 only when a field changed)

/v1/audiences

OperationRouteScopesRate classIdempotency-KeySummary
broadcasts.listAudiencesGET /v1/audiencesaudiences:readreadnoThe tenant's audiences with member counts and consent coverage
broadcasts.createAudiencePOST /v1/audiencesaudiences:writewriterequiredCreate a static audience through the platform write path; a duplicate name is 409 conflict
broadcasts.getAudienceGET /v1/audiences/{audience_id}audiences:readreadnoOne audience with member count, consent coverage and the last import
broadcasts.listAudienceMembersGET /v1/audiences/{audience_id}/membersaudiences:readreadnoMembers as contact ids and hashes with consent and status (never an address, D8)
broadcasts.removeAudienceMemberDELETE /v1/audiences/{audience_id}/members/{contact_id}audiences:writewritenoRemove a member through the platform write path; the consent history is kept
broadcasts.createAudienceImportPOST /v1/audiences/{audience_id}/importsaudiences:writeimportrequiredOpen a CSV import with its consent block (S20: a request without one is 422) and a presigned upload URL (15 minutes, at most 52428800 bytes)
broadcasts.startAudienceImportPOST /v1/audiences/{audience_id}/imports/{import_id}/startaudiences:writeimportnoStart the import workflow once the file is uploaded (409 conflict while no object exists)
broadcasts.getAudienceImportGET /v1/audiences/{audience_id}/imports/{import_id}audiences:readreadnoImport state with row counts and the first 20 failures (row numbers and codes only)

/v1/segments

OperationRouteScopesRate classIdempotency-KeySummary
broadcasts.listSegmentsGET /v1/segmentsaudiences:readreadnoThe tenant's segments with their last counts
broadcasts.createSegmentPOST /v1/segmentsaudiences:writewriterequiredCreate a segment over an audience (conditions nest 3 deep, at most 20 conditions and 8 excluded segments; unknown fields or operators are 422)
broadcasts.getSegmentGET /v1/segments/{segment_id}audiences:readreadnoOne segment with its conditions and last count
broadcasts.updateSegmentPATCH /v1/segments/{segment_id}audiences:writewritenoRename a segment or change its conditions; 409 conflict while a scheduled or running broadcast uses it
broadcasts.previewSegmentPOST /v1/segments/{segment_id}/previewaudiences:readpreviewnoCount the segment up to 100000 (a lower bound above) and return 20 contact ids; cached 5 minutes