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

# Send Bulk Emails

> Send up to 20 emails in a single request. Use `fallback` to set default values shared across all messages.



## OpenAPI

````yaml /openapi.documented.yml post /emails/bulk
openapi: 3.1.0
info:
  title: Nuntly REST API 1.x
  version: 1.0.0-alpha.20
  description: Nuntly REST API definition
  termsOfService: https://nuntly.com/legal/terms-of-service
  contact:
    name: Nuntly Support
    url: https://nuntly.com/docs
    email: support@nuntly.com
servers:
  - description: Nuntly API endpoint
    url: https://api.nuntly.com
security:
  - bearerAuth: []
tags:
  - name: API Keys
    description: >-
      Create and revoke API keys used to authenticate requests to the Nuntly
      API.
  - name: Agents
    description: >-
      Read and write persistent state for an AI agent, optionally scoped to a
      specific inbox or thread.
  - name: Domains
    description: >-
      Add and verify sending and receiving domains. Manage DKIM records, SPF
      configuration, and enable inbound email routing.
  - name: Emails
    description: >-
      Send transactional emails, retrieve sending history, and track delivery
      status per message.
  - name: Inboxes
    description: >-
      Create email inboxes at a specific address on a verified receiving domain.
      Assign inboxes to namespaces or AI agents.
  - name: Messages
    description: >-
      Access received messages, download attachments, and send replies or
      forwards from an inbox.
  - name: Namespaces
    description: >-
      Isolate inboxes by tenant, client, or agent using namespaces. Use an
      external ID to map namespaces to your own data model.
  - name: Organizations
    description: >-
      Manage your organization profile, team members, and account-level
      settings.
  - name: Threads
    description: >-
      Browse email conversations grouped by subject. Mark threads as read or
      spam, and assign them to an agent.
  - name: Webhooks
    description: >-
      Register HTTP endpoints to receive real-time delivery events such as
      bounces, opens, and clicks.
  - name: Webhooks Events
    description: >-
      Inspect webhook event history and replay failed deliveries for debugging
      or recovery.
  - name: Webhooks Hook
    description: >-
      Endpoint your server implements to receive webhook events. Not a Nuntly
      API endpoint - this documents the shape your handler must accept.
externalDocs:
  description: Nuntly API Documentation
  url: https://nuntly.com/docs
paths:
  /emails/bulk:
    post:
      tags:
        - Emails
      summary: Send Bulk Emails
      description: >-
        Send up to 20 emails in a single request. Use `fallback` to set default
        values shared across all messages.
      operationId: send-bulk-emails
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          description: >-
            Unique key to ensure the request is processed at most once. UUIDv4
            recommended.
          schema:
            type: string
            minLength: 1
            maxLength: 255
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBulkEmailsRequest'
      responses:
        '202':
          description: Request accepted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/CreateBulkEmailsResponse'
                required:
                  - data
                additionalProperties: false
        '500':
          description: An error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-codeSamples:
        - lang: cURL
          source: |-
            curl -X POST 'https://api.nuntly.com/emails/bulk' \
              -H 'Authorization: Bearer apk_xxx' \
              -H 'Content-Type: application/json' \
              -d '{"emails":[{"from":"Tomlinson AI <ray@info.tomlinson.ai>","to":"brian67@gmail.com","subject":"Verify your email address","text":"Thank you for signing up! Please verify your email address."}]}'
        - lang: JavaScript
          source: |-
            import { Nuntly } from '@nuntly/sdk';

            const client = new Nuntly({
              apiKey: process.env['NUNTLY_API_KEY'],
            });

            const response = await client.emails.bulk.send({
              emails: [{ from: 'Tomlinson AI <ray@info.tomlinson.ai>', to: 'brian67@gmail.com', subject: 'Verify your email address', text: 'Thank you for signing up! Please verify your email address.' }],
            });
        - lang: Java
          source: >-
            import com.nuntly.sdk.Nuntly;

            import com.nuntly.sdk.ClientOptions;

            import com.nuntly.sdk.models.*;


            var nuntly = Nuntly.create(ClientOptions.builder()
                .apiKey(System.getenv("NUNTLY_API_KEY"))
                .build());

            var response =
            nuntly.emails().bulk().send(CreateBulkEmailsRequest.builder()
                .emails(List.of(CreateBulkEmail.builder().from("Tomlinson AI <ray@info.tomlinson.ai>").to("brian67@gmail.com").subject("Verify your email address").text("Thank you for signing up! Please verify your email address.").build()))
                .build());
components:
  schemas:
    CreateBulkEmailsRequest:
      type: object
      required:
        - emails
      properties:
        fallback:
          $ref: '#/components/schemas/CreateBulkFallback'
          description: >-
            Used as a fallback field email value if no value is present in
            emails.
        emails:
          description: The bulk emails to send.
          type: array
          items:
            $ref: '#/components/schemas/CreateBulkEmail'
    CreateBulkEmailsResponse:
      type: object
      required:
        - emails
      properties:
        id:
          description: The bulk id
          type: string
          examples:
            - em_01ka8k8s80gvx9604cn9am5st4
        emails:
          type: array
          items:
            type: object
            required:
              - status
            properties:
              id:
                type: string
              status:
                $ref: '#/components/schemas/EmailStatus'
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/Error'
          description: >-
            This object provide you additional information about errors
            encountered while performing the operation
    CreateBulkFallback:
      type: object
      properties:
        from:
          description: The e-mail address of the sender
          type: string
          examples:
            - Tomlinson AI <ray@info.tomlinson.ai>
        to:
          description: The primary recipient(s) of the email
          anyOf:
            - type: array
              items:
                type: string
            - type: string
          examples:
            - brian67@gmail.com
            - - carlo43@gmail.com
              - pink42@yahoo.com
        cc:
          description: The carbon copy recipient(s) of the email
          anyOf:
            - type: array
              items:
                type: string
            - type: string
          examples:
            - carlo43@gmail.com
        bcc:
          description: The blind carbon copy recipient(s) of the email
          anyOf:
            - type: array
              items:
                type: string
            - type: string
          examples:
            - archive@company.com
        replyTo:
          description: >-
            The email address where replies should be sent. If a recipient
            replies, the response will go to this address instead of the
            sender's email address
          anyOf:
            - type: array
              items:
                type: string
            - type: string
          examples:
            - support@company.com
        subject:
          description: The subject of the e-mail
          type: string
          examples:
            - Verify your email address
        text:
          description: The plaintext version of the email
          type: string
          examples:
            - Thank you for signing up! Please verify your email address.
        html:
          description: The HTML version of the email
          type: string
          examples:
            - >-
              <h1>Welcome 🎉</h1><p>Thank you for signing up! Please verify your
              email address.</p>
        headers:
          description: The headers to add to the email
          type: object
          additionalProperties: true
        tags:
          description: The tags to add to the email
          type: array
          items:
            $ref: '#/components/schemas/Tag'
        variables:
          description: The variables for the template
          type: object
          additionalProperties: true
    CreateBulkEmail:
      type: object
      properties:
        from:
          description: The e-mail address of the sender
          type: string
          examples:
            - Tomlinson AI <ray@info.tomlinson.ai>
        to:
          description: The primary recipient(s) of the email
          anyOf:
            - type: array
              items:
                type: string
            - type: string
          examples:
            - brian67@gmail.com
            - - carlo43@gmail.com
              - pink42@yahoo.com
        cc:
          description: The carbon copy recipient(s) of the email
          anyOf:
            - type: array
              items:
                type: string
            - type: string
          examples:
            - carlo43@gmail.com
        bcc:
          description: The blind carbon copy recipient(s) of the email
          anyOf:
            - type: array
              items:
                type: string
            - type: string
          examples:
            - archive@company.com
        replyTo:
          description: >-
            The email address where replies should be sent. If a recipient
            replies, the response will go to this address instead of the
            sender's email address
          anyOf:
            - type: array
              items:
                type: string
            - type: string
          examples:
            - support@company.com
        subject:
          description: The subject of the e-mail
          type: string
          examples:
            - Verify your email address
        text:
          description: The plaintext version of the email
          type: string
          examples:
            - Thank you for signing up! Please verify your email address.
        html:
          description: The HTML version of the email
          type: string
          examples:
            - >-
              <h1>Welcome 🎉</h1><p>Thank you for signing up! Please verify your
              email address.</p>
        headers:
          description: The headers to add to the email
          type: object
          additionalProperties: true
        tags:
          description: The tags to add to the email
          type: array
          items:
            $ref: '#/components/schemas/Tag'
        variables:
          description: The variables for the template
          type: object
          additionalProperties: true
    EmailStatus:
      type: string
      enum:
        - queued
        - scheduled
        - processed
        - failed
        - sending
        - sent
        - delivered
        - bounced
        - complained
        - canceled
        - rejected
    Error:
      type: object
      required:
        - status
        - code
        - title
      properties:
        status:
          description: >-
            The HTTP status code generated by the origin server for this
            occurrence of the error.
          type: number
        code:
          description: An API specific code representing the type of error.
          type: string
        title:
          description: A short, human-readable summary of the error type.
          type: string
        details:
          description: >-
            A (best effort) human readable explanation specific to this
            occurrence of the error.
          type: object
          additionalProperties: true
    Tag:
      type: object
      required:
        - name
        - value
      properties:
        name:
          description: The name of the tag
          type: string
          examples:
            - category
        value:
          description: The tag to add to the email
          type: string
          examples:
            - transactional
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key (format apk_...)
      description: >-
        Use an API key from https://nuntly.com/api-keys. Required on every
        endpoint.

````