> ## 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 transactional emails in batch

> Sends multiple transactional emails in a single API request for better performance.



## OpenAPI

````yaml /openapi.json post /send/transactional/batch
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/transactional/batch:
    post:
      tags:
        - Sending
      summary: Send transactional emails in batch
      description: >-
        Sends multiple transactional emails in a single API request for better
        performance.
      operationId: Sending_transactionalBatch
      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/SendMessageBatchRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendMessageBatchResponse'
        '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_message_batch_request = Helo::SendMessageBatchRequest.new(
              requests: [Helo::SendMessageRequest.new(to: [], cc: [], bcc: [], reply_to: [], subject: "test-subject", html: "test-html", text: "test-text", template: {}, tracking: {}, attachments: [], tags: ["example1", "example2"], headers: {}, metadata: {})]
            )

            Helo::Sending.transactional_batch(send_message_batch_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.transactionalBatch(
              {
                requests: [
                  {
                    from: { email: "test@example.com", name: "test-name" },
                    to: [{ email: "test@example.com", name: "test-name" }],
                    cc: [{ email: "test@example.com", name: "test-name" }],
                    bcc: [{ email: "test@example.com", name: "test-name" }],
                    replyTo: [{ email: "test@example.com", name: "test-name" }],
                    subject: "test-subject",
                    html: "test-html",
                    text: "test-text",
                    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: {},
                  },
                ],
              },
              {
                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.SendMessageBatchRequest{\n\t\tRequests: []helo.SendMessageRequest{{From: helo.MailAddress{Email: \"test@example.com\", Name: \"test-name\"}, To: []helo.MailAddress{{Email: \"test@example.com\", Name: \"test-name\"}}, Subject: \"test-subject\", Html: \"test-html\", Text: \"test-text\", Tags: []string{\"example1\", \"example2\"}}},\n\t}\n\topts := &helo.SendingTransactionalBatchOptions{\n\t\tChannelID: \"550e8400-e29b-41d4-a716-446655440000\",\n\t\tIdempotencyKey: \"example\",\n\t}\n\tresult, err := client.Sending.TransactionalBatch(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.TransactionalBatch(new
            SendMessageBatchRequest

            {
                Requests =
                [
                    new SendMessageRequest
                    {
                        From = new MailAddress { Email = "from@yourdomain.com", Name = "From name" },
                        To = [new MailAddress { Email = "first@example.com" }],
                        Subject = "Hello from Helo",
                        Html = "<html><body><h1>Hi there, new friend.</h1><p>This is a test message, delivered with <3 by Helo. </p></body></html>",
                    },
                    new SendMessageRequest
                    {
                        From = new MailAddress { Email = "from@yourdomain.com", Name = "From name" },
                        To = [new MailAddress { Email = "second@example.com" }],
                        Subject = "Hello from Helo",
                        Html = "<html><body><h1>Hi there, new friend.</h1><p>This is a test message, delivered with <3 by Helo. </p></body></html>",
                    },
                ],
            }, 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.transactional_batch(
                requests=[
                    {
                        "from": {"email": "from@yourdomain.com", "name": "From name"},
                        "to": [{"email": "first@example.com"}],
                        "subject": "Hello from Helo",
                        "html": "<html><body><h1>Hi there, new friend.</h1><p>This is a test message, delivered with <3 by Helo. </p></body></html>",
                        "text": "This is a test message, delivered with <3 by Helo."
                    },
                    {
                        "from": {"email": "from@yourdomain.com", "name": "From name"},
                        "to": [{"email": "second@example.com"}],
                        "subject": "Hello from Helo",
                        "html": "<html><body><h1>Hi there, new friend.</h1><p>This is a test message, delivered with <3 by Helo. </p></body></html>",
                        "text": "This is a test message, delivered with <3 by Helo."
                    }
                ],
                channel_id="your-channel-id",
            )
components:
  schemas:
    SendMessageBatchRequest:
      type: object
      properties:
        requests:
          type: array
          items:
            $ref: '#/components/schemas/SendMessageRequest'
      required:
        - requests
    SendMessageBatchResponse:
      type: object
      properties:
        responses:
          type: array
          items:
            $ref: '#/components/schemas/SendMessageResponse'
      required:
        - responses
    SendMessageRequest:
      type: object
      properties:
        from:
          $ref: '#/components/schemas/MailAddress'
        to:
          type: array
          items:
            $ref: '#/components/schemas/MailAddress'
        cc:
          type: array
          items:
            $ref: '#/components/schemas/MailAddress'
        bcc:
          type: array
          items:
            $ref: '#/components/schemas/MailAddress'
        replyTo:
          type: array
          items:
            $ref: '#/components/schemas/MailAddress'
        subject:
          type: string
        html:
          type: string
        text:
          type: string
        template:
          type: object
          properties:
            subject:
              type: string
            html:
              type: string
            text:
              type: string
            inlineStyles:
              type: boolean
            data:
              type: object
              description: Model used for template placeholder replacement
        tracking:
          type: object
          properties:
            opens:
              type: boolean
            links:
              type: boolean
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
        tags:
          type: array
          items:
            type: string
        headers:
          type: object
        metadata:
          type: object
      required:
        - from
        - to
    SendMessageResponse:
      type: object
      anyOf:
        - $ref: '#/components/schemas/SendMessageAcceptedResponse'
        - $ref: '#/components/schemas/SendMessageFailedResponse'
      discriminator:
        propertyName: status
        mapping:
          accepted:
            $ref: '#/components/schemas/SendMessageAcceptedResponse'
          delayed:
            $ref: '#/components/schemas/SendMessageAcceptedResponse'
          failed:
            $ref: '#/components/schemas/SendMessageFailedResponse'
      required:
        - status
    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'
    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
    SendMessageAcceptedResponse:
      type: object
      properties:
        status:
          type: string
        messageId:
          type: string
          format: uuid
        suppressions:
          type: array
          items:
            type: string
    SendMessageFailedResponse:
      properties:
        status:
          type: string
        errorCode:
          type: string
        errorMessage:
          type: string
      required:
        - status
        - errorCode
        - errorMessage
    ValidationError:
      description: A single field validation error.
      required:
        - message
      type: object
      properties:
        message:
          description: Description of the validation failure.
          type: string
    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).
  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

````