> ## Documentation Index
> Fetch the complete documentation index at: https://docs.helohq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Send a broadcast email

> Sends a broadcast email to multiple recipients for marketing or announcement purposes.



## OpenAPI

````yaml /openapi.json post /send/broadcast
openapi: 3.1.0
info:
  description: Helo API
  version: 1.0.0-beta.1
  title: Helo API
servers:
  - url: https://api.helohq.com
security: []
tags:
  - name: Activity
    description: >-
      Track and retrieve message activity, including messages, delivery and
      engagement events.
  - name: Broadcasts
    description: Manage and track broadcast email campaigns.
  - name: Channels
    description: Create and manage communication channels for organizing messages.
  - name: Domains
    description: Register, verify, and manage domains for email sending.
  - name: Sending
    description: Send transactional and broadcast emails.
  - name: Statistics
    description: Access activity statistics.
  - name: Webhooks
    description: Create and manage webhooks for event notifications.
paths:
  /send/broadcast:
    post:
      tags:
        - Sending
      summary: Send a broadcast email
      description: >-
        Sends a broadcast email to multiple recipients for marketing or
        announcement purposes.
      operationId: Sending_broadcast
      parameters:
        - name: X-Helo-Channel-Id
          in: header
          description: >-
            Used to specify a channel ID for sending when using an account-level
            API credential.
          schema:
            type: string
            format: uuid
        - name: X-Helo-Idempotency-Key
          in: header
          description: >-
            A unique identifier used to prevent duplicate messages being sent
            when retrying failed requests.
          schema:
            type: string
            maxLength: 256
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendBroadcastRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendBroadcastResponse'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
      security:
        - bearerAuth: []
      x-codeSamples:
        - lang: ruby
          source: >-
            Helo.configure do |config|
              config.api_key = ENV.fetch("HELO_API_KEY")
            end


            send_broadcast_request = Helo::SendBroadcastRequest.new(
              from: Helo::MailAddress.new(email: "test-email", name: "test-name"),
              reply_to: [Helo::MailAddress.new(email: "test-email", name: "test-name")],
              template: {},
              tracking: {},
              attachments: [Helo::Attachment.new(content: "test-content", content_id: "test-contentId", content_type: "test-contentType", file_name: "test-fileName", disposition: Helo::AttachmentDisposition::ATTACHMENT)],
              tags: ["example1", "example2"],
              headers: {},
              metadata: {},
              messages: []
            )

            Helo::Sending.broadcast(send_broadcast_request, channel_id:
            "550e8400-e29b-41d4-a716-446655440000", idempotency_key: "example")
        - lang: javascript
          source: |-
            import Helo from "@helo-email/sdk";

            const apiKey = process.env.HELO_API_KEY;
            const helo = new Helo(apiKey);

            const result = await helo.sending.broadcast(
              {
                from: { email: "test@example.com", name: "test-name" },
                replyTo: [{ email: "test@example.com", name: "test-name" }],
                template: {
                  subject: "test-subject",
                  html: "test-html",
                  text: "test-text",
                  inlineStyles: true,
                  data: {},
                },
                tracking: { opens: true, links: true },
                attachments: [
                  {
                    content: "test-content",
                    contentId: "test-contentId",
                    contentType: "test-contentType",
                    fileName: "test-fileName",
                    disposition: Helo.AttachmentDisposition.ATTACHMENT,
                  },
                ],
                tags: ["example1", "example2"],
                headers: {},
                metadata: {},
                messages: [
                  {
                    to: [{ email: "test@example.com", name: "test-name" }],
                    cc: [{ email: "test@example.com", name: "test-name" }],
                    bcc: [{ email: "test@example.com", name: "test-name" }],
                    tags: ["example1", "example2"],
                    headers: {},
                    metadata: {},
                    data: {},
                  },
                ],
              },
              {
                channelId: "550e8400-e29b-41d4-a716-446655440000",
                idempotencyKey: "example",
              },
            );
        - lang: go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"log\"\n\t\"os\"\n\n\t\"github.com/helo-email/helo-sdk-go\"\n)\n\nfunc main() {\n\tclient := helo.NewHelo(os.Getenv(\"HELO_API_KEY\"))\n\tctx := context.Background()\n\n\tparams := &helo.SendBroadcastRequest{\n\t\tFrom: helo.MailAddress{Email: \"test@example.com\", Name: \"test-name\"},\n\t\tTemplate: helo.SendBroadcastRequestTemplate{Subject: \"test-subject\", Html: \"test-html\", Text: \"test-text\", InlineStyles: true},\n\t\tTags: []string{\"example1\", \"example2\"},\n\t\tMessages: []helo.SendBroadcastRequestMessage{{To: []helo.MailAddress{{Email: \"test@example.com\", Name: \"test-name\"}}, Tags: []string{\"example1\", \"example2\"}}},\n\t}\n\topts := &helo.SendingBroadcastOptions{\n\t\tChannelID: \"550e8400-e29b-41d4-a716-446655440000\",\n\t\tIdempotencyKey: \"example\",\n\t}\n\tresult, err := client.Sending.Broadcast(ctx, params, opts)\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\t_ = result\n}"
        - lang: csharp
          source: |-
            using HeloEmail.Sdk;
            using HeloEmail.Sdk.Sending;

            var response = await helo.Sending.Broadcast(new SendBroadcastRequest
            {
                From = new MailAddress { Email = "from@yourdomain.com", Name = "From name" },
                Template = new MessageTemplate
                {
                    Subject = "Product update",
                    Html = "<p>Here's what's new this month…</p>",
                },
                Messages =
                [
                    new BroadcastMessage { To = [new MailAddress { Email = "first@example.com" }] },
                    new BroadcastMessage { To = [new MailAddress { Email = "second@example.com" }] },
                ],
            }, channelId: "your-channel-id");
        - lang: python
          source: |-
            import sdk_helo_email as helo

            client = helo.Helo()  # reads HELO_API_KEY from the environment

            response = client.sending.broadcast(
                from_={"email": "from@yourdomain.com", "name": "From name"},
                template={"subject": "Product update", "html": "<p>Here's what's new this month.</p>"},
                messages=[
                    {"to": [{"email": "first@example.com"}]},
                    {"to": [{"email": "second@example.com"}]},
                ],
                channel_id="your-channel-id",
            )
components:
  schemas:
    SendBroadcastRequest:
      type: object
      properties:
        from:
          $ref: '#/components/schemas/MailAddress'
        replyTo:
          type: array
          items:
            $ref: '#/components/schemas/MailAddress'
          description: Reply-to addresses.
        template:
          type: object
          properties:
            subject:
              type: string
              description: >-
                Subject line. Max 256 characters. Supports `{{variable}}`
                syntax.
            html:
              type: string
              description: HTML body. Supports `{{variable}}` syntax.
            text:
              type: string
              description: Plain-text fallback body. Supports `{{variable}}` syntax.
            inlineStyles:
              type: boolean
              description: When true, CSS styles are inlined into the HTML before sending.
            data:
              type: object
              description: >-
                Default template variables applied to every message.
                Message-level `data` values override these defaults.
          required:
            - subject
          description: >-
            Email template applied to every message in the broadcast. At least
            one of `html` or `text` is required.
        tracking:
          type: object
          properties:
            opens:
              type: boolean
              description: >-
                Track email opens. Defaults to the channel setting when not
                provided.
            links:
              type: boolean
              description: >-
                Track link clicks. Defaults to the channel setting when not
                provided.
          description: Override channel-level open and link tracking settings.
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
          description: >-
            File attachments included with every message in the broadcast.
            Executable and potentially harmful file types are blocked.
        tags:
          type: array
          items:
            type: string
          description: >-
            Up to 5 tags for filtering and analytics. Allowed characters are
            letters, numbers, hyphens, and underscores. Max 100 characters per
            tag.
        headers:
          type: object
          description: >-
            Custom email headers applied to every message. Total size of all
            headers combined must not exceed 5,000 characters.
        metadata:
          type: object
          description: >-
            Custom key/value metadata stored with the broadcast. Max 10 fields;
            keys max 50 characters, values max 100 characters.
        messages:
          type: array
          items:
            type: object
            properties:
              to:
                type: array
                items:
                  $ref: '#/components/schemas/MailAddress'
                description: >-
                  Primary recipients. At least one required. Combined with `cc`
                  and `bcc`, total recipients per message must not exceed 50.
              cc:
                type: array
                items:
                  $ref: '#/components/schemas/MailAddress'
                description: Carbon copy recipients.
              bcc:
                type: array
                items:
                  $ref: '#/components/schemas/MailAddress'
                description: Blind carbon copy recipients.
              tags:
                type: array
                items:
                  type: string
                description: Message-specific tags. Merged with broadcast-level tags.
              headers:
                type: object
                description: Message-specific headers. Merged with broadcast-level headers.
              metadata:
                type: object
                description: >-
                  Message-specific metadata. Merged with broadcast-level
                  metadata.
              data:
                type: object
                description: >-
                  Message-specific template variables. Merged with and overrides
                  template-level `data`.
            required:
              - to
          description: One entry per outbound email. At least one message is required.
      required:
        - from
        - template
        - messages
    SendBroadcastResponse:
      type: object
      properties:
        status:
          type: string
          description: >-
            `accepted` — broadcast queued successfully. `failed` — validation or
            account error (see `errorCode`). `delayed` — transient submission
            error, will be retried automatically.
        broadcastId:
          type: string
          format: uuid
          description: >-
            Unique identifier for the broadcast. Use this to track progress via
            `GET /broadcasts/{id}`.
    MailAddress:
      type: object
      properties:
        email:
          type: string
          description: Email address. Max 254 characters.
        name:
          type: string
          description: Display name shown to recipients in their email client.
      required:
        - email
    Attachment:
      type: object
      properties:
        content:
          type: string
          format: byte
          description: Base64-encoded file content.
        contentId:
          type: string
          description: >-
            Used to reference inline images in HTML (e.g. `cid:logo`). Only
            applicable when `disposition` is `inline`.
        contentType:
          type: string
          description: >-
            MIME type (e.g. `application/pdf`). Inferred from the file extension
            if not provided.
        fileName:
          type: string
          description: >-
            File name including extension (e.g. `report.pdf`). Executable and
            potentially harmful file types are blocked.
        disposition:
          $ref: '#/components/schemas/AttachmentDisposition'
      required:
        - content
        - fileName
        - disposition
    ErrorResponse:
      description: Standard error response body.
      type: object
      properties:
        type:
          description: A URI reference identifying the problem type.
          type: string
        title:
          description: Short, human-readable summary of the problem.
          type: string
        instance:
          description: URI reference identifying the specific occurrence of the problem.
          type: string
        status:
          description: HTTP status code.
          type: integer
          format: int32
        code:
          description: Application-specific error code.
          type: string
        detail:
          description: Human-readable explanation of this specific occurrence.
          type: string
        requestId:
          description: Unique request ID, useful for support correlation.
          type: string
        errors:
          description: Field-level validation errors, keyed by field name.
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/ValidationError'
    AttachmentDisposition:
      enum:
        - attachment
        - inline
      description: >-
        How the attachment is presented. Use `attachment` for downloadable files
        and `inline` for embedded content (e.g. images referenced in HTML).
    ValidationError:
      description: A single field validation error.
      required:
        - message
      type: object
      properties:
        message:
          description: Description of the validation failure.
          type: string
  responses:
    '401':
      description: Unauthorized
    '403':
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    '422':
      description: Unprocessable Entity
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    '500':
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````