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

# Send a batch of emails

> Sends up to 100 messages in one call, each with the fields of a send (no attachments), and answers `202` with `data`: one message per item, in order, in the extended shape. The body is a JSON array of the messages, or `{ "emails": [...] }`, at most 10 MiB. By default the batch is all or nothing: every item is judged first, and any refusal answers `422 batch_invalid` naming each refused item by its `index`, with nothing sent or charged. With `Tawked-Batch-Validation: permissive` the valid items are sent and the refused ones listed in `errors` beside `data`. An item whose every recipient is suppressed is not a refusal: it is answered `failed` and not charged. The batch counts as one request against the account's rate and is charged in one go; the daily limit and the balance apply to all its e-mails together.

Guide: [Sending in batches](https://docs.tawked.com/email/batch.md)


## OpenAPI

````yaml https://tawked.com/openapi.json post /v1/email/messages/batch
openapi: 3.1.0
info:
  title: Tawked API
  version: 2026-09
  summary: >-
    Tawked Verify: OTP verification for Saudi mobile numbers over SMS, in two
    calls. Tawked Notifications: WhatsApp template messages from the
    application's own number. Tawked Email: transactional e-mail from the
    application's own verified domain. Tawked Chat: the conversation menus a
    connected app adds beside the conversations of its connection's application,
    and the auto-attendant it sets up there. The Partner API for platforms that
    run Tawked Verify for their merchants.
  description: >-
    The public API of Tawked, a Saudi messaging platform: Tawked Verify
    (one-time codes), Tawked Notifications (WhatsApp templates from the
    application's own number), Tawked Email (transactional e-mail from the
    application's own domain) and the Partner API. Tawked Verify is an OTP
    verification API for Saudi numbers. One call sends a one-time code by SMS to
    a Saudi mobile number, and a second call checks it. SAR 0.09 per SMS code
    sent, prepaid; a send the network refuses is refunded. Authenticate with a
    Bearer API key from the dashboard (tk_live_ for production, tk_test_ for the
    sandbox, tk_partner_ for partners, tk_partner_test_ for the partner
    sandbox). Partners (tk_partner_) provision a Verify application per merchant
    under /v1/partner/applications and name it as application on every Verify
    call. Both /v1/... and /api/v1/... answer identically. Rate limit: 120
    requests per minute per key.
  termsOfService: https://tawked.com/en/terms
  license:
    name: Proprietary (Tawked terms of service)
    url: https://tawked.com/en/terms
  contact:
    name: Tawked support
    email: support@tawked.com
    url: https://tawked.com/en/contact
servers:
  - url: https://tawked.com
    description: Production (the sandbox is a tk_test_ key on the same host)
  - url: https://tawked.com/api
    description: The same API under /api/v1/..., kept for older integrations
security:
  - bearerKey: []
  - headerKey: []
tags:
  - name: Verify
    x-group: Verify
    description: Send and check one-time codes.
  - name: WhatsApp
    x-group: Notifications
    description: >-
      Tawked Notifications: send approved WhatsApp templates through the number
      connected to an application. An application in review or approved connects
      its own number from the dashboard.
  - name: Email
    x-group: Email
    description: >-
      Tawked Email: send transactional e-mail from an address on a verified
      domain of the application, to up to 50 recipients a message, in batches or
      scheduled, and read and list what was sent. Live keys only.
  - name: Chat
    x-group: Chat
    description: >-
      Tawked Chat: the conversation menus a connected app adds beside the
      conversations of its connection's application, and reads, changes and
      removes, with `chat:menus`; and the application's auto-attendant, which a
      connected app sets up, publishes and switches on or off, with
      `chat:attendant`. A connected app's key only; a business adds its own
      menus and builds its auto-attendant in the console.
  - name: Partner
    x-group: Partner API
    description: >-
      For platforms that run Tawked Verify for their merchants: provision a
      Verify application per merchant, keep its brand and verify settings
      current, switch it off and on, and read usage and the code log. Partner
      keys (tk_partner_) only; every Verify operation then takes `application`
      with the partner's own id for the application.
  - name: Webhooks
    x-group: Webhooks
    description: >-
      The events Tawked sends to your endpoint: an application's verification
      outcomes and message statuses, and a partner account's lifecycle, balance
      and opt-in verification events. Every delivery is signed the same way and
      retried the same way.
externalDocs:
  description: Developer docs, with code samples
  url: https://docs.tawked.com
paths:
  /v1/email/messages/batch:
    post:
      tags:
        - Email
      summary: Send a batch of emails
      description: >-
        Sends up to 100 messages in one call, each with the fields of a send (no
        attachments), and answers `202` with `data`: one message per item, in
        order, in the extended shape. The body is a JSON array of the messages,
        or `{ "emails": [...] }`, at most 10 MiB. By default the batch is all or
        nothing: every item is judged first, and any refusal answers `422
        batch_invalid` naming each refused item by its `index`, with nothing
        sent or charged. With `Tawked-Batch-Validation: permissive` the valid
        items are sent and the refused ones listed in `errors` beside `data`. An
        item whose every recipient is suppressed is not a refusal: it is
        answered `failed` and not charged. The batch counts as one request
        against the account's rate and is charged in one go; the daily limit and
        the balance apply to all its e-mails together.
      operationId: email_batch
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          description: >-
            A 1 to 256 printable-ASCII-character key for the whole batch.
            Replaying it with the same batch answers the first `202` as it was,
            with `Idempotent-Replayed: true`: nothing is sent or charged again;
            another batch under it answers `409 idempotency_key_reused`. A
            batch's keys and single sends' keys are separate: the same key used
            on both is two keys. A key is free again after 24 hours.
          schema:
            type: string
        - name: Tawked-Batch-Validation
          in: header
          required: false
          description: >-
            `strict` (the default) or `permissive`. Resend's own name for it,
            `x-batch-validation`, is read the same way.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                emails:
                  type: array
                  description: >-
                    The messages, 1 to 100: each an object with the fields of a
                    send (`from`, `to`, `cc`, `bcc`, `reply_to`, `subject`,
                    `html`, `text`, `reference`, `headers`, `tags`,
                    `scheduled_at`), never `attachments`. The body may also be
                    the array itself, as Resend takes it.
                application:
                  type: string
                  description: >-
                    Partner keys only: the application, in the query string
                    (`?application=…`) or on every item, the same for all.
              required:
                - emails
      responses:
        '202':
          description: Accepted / Accepted, permissive
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        status:
                          type: string
                        from:
                          type: object
                          properties:
                            name:
                              type: string
                            address:
                              type: string
                        to:
                          type: array
                          items:
                            type: string
                        cc:
                          type: array
                          items:
                            type:
                              - string
                              - 'null'
                        bcc:
                          type: array
                          items:
                            type:
                              - string
                              - 'null'
                        reply_to:
                          type: array
                          items:
                            type:
                              - string
                              - 'null'
                        subject:
                          type: string
                        reference:
                          type: string
                        tags:
                          type: array
                          items:
                            type: object
                            properties:
                              name:
                                type: string
                              value:
                                type: string
                        scheduled_at:
                          type:
                            - string
                            - 'null'
                        recipients:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                              address:
                                type: string
                              name:
                                type:
                                  - string
                                  - 'null'
                              type:
                                type: string
                              status:
                                type: string
                        price_halalas:
                          type: integer
                        cost:
                          type: object
                          properties:
                            emails:
                              type: integer
                            suppressed:
                              type: integer
                            free:
                              type: integer
                            billed:
                              type: integer
                            halalas:
                              type: string
                        created_at:
                          type: string
                          format: date-time
                        mode:
                          type: string
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        index:
                          type: integer
                        error:
                          type: string
                        message:
                          type: string
                        field:
                          type: string
                        field_index:
                          type: integer
              examples:
                accepted:
                  summary: Accepted
                  value:
                    data:
                      - id: 0199f1c2-8b01-7a20-9c3d-4e5f6a7b8c9d
                        status: accepted
                        from:
                          name: متجر أكمي
                          address: orders@acme.sa
                        to:
                          - sara@example.com
                        cc: []
                        bcc: []
                        reply_to: []
                        subject: طلبك رقم 1042 قيد التجهيز
                        reference: order-1042
                        tags:
                          - name: category
                            value: order
                        scheduled_at: null
                        recipients:
                          - id: 0199f1c2-8b02-7d41-8e5f-6a7b8c9d0e1f
                            address: sara@example.com
                            name: null
                            type: to
                            status: queued
                        price_halalas: 0
                        cost:
                          emails: 1
                          suppressed: 0
                          free: 1
                          billed: 0
                          halalas: '0'
                        created_at: '2026-10-21T12:00:00+03:00'
                        mode: live
                      - id: 0199f1c2-8b03-7b62-9f7a-8b9c0d1e2f3a
                        status: accepted
                        from:
                          name: متجر أكمي
                          address: orders@acme.sa
                        to:
                          - ali@example.com
                        cc: []
                        bcc: []
                        reply_to: []
                        subject: طلبك رقم 1043 قيد التجهيز
                        reference: order-1043
                        tags:
                          - name: category
                            value: order
                        scheduled_at: null
                        recipients:
                          - id: 0199f1c2-8b04-7c83-8a9b-0c1d2e3f4a5b
                            address: ali@example.com
                            name: null
                            type: to
                            status: queued
                        price_halalas: 0
                        cost:
                          emails: 1
                          suppressed: 0
                          free: 1
                          billed: 0
                          halalas: '0'
                        created_at: '2026-10-21T12:00:00+03:00'
                        mode: live
                accepted_permissive:
                  summary: Accepted, permissive
                  value:
                    data:
                      - id: 0199f1c2-8b01-7a20-9c3d-4e5f6a7b8c9d
                        status: accepted
                        from:
                          name: متجر أكمي
                          address: orders@acme.sa
                        to:
                          - sara@example.com
                        cc: []
                        bcc: []
                        reply_to: []
                        subject: طلبك رقم 1042 قيد التجهيز
                        reference: order-1042
                        tags:
                          - name: category
                            value: order
                        scheduled_at: null
                        recipients:
                          - id: 0199f1c2-8b02-7d41-8e5f-6a7b8c9d0e1f
                            address: sara@example.com
                            name: null
                            type: to
                            status: queued
                        price_halalas: 0
                        cost:
                          emails: 1
                          suppressed: 0
                          free: 1
                          billed: 0
                          halalas: '0'
                        created_at: '2026-10-21T12:00:00+03:00'
                        mode: live
                    errors:
                      - index: 1
                        error: invalid_destination
                        message: '`to[0]` is not a valid e-mail address'
                        field: to
                        field_index: 0
          headers:
            RateLimit-Limit:
              description: >-
                The account's requests a second on the e-mail routes, for all
                its applications, keys and the SMTP relay together: max(10, its
                daily limit / 1000).
              schema:
                type: string
                pattern: ^[0-9]+$
            RateLimit-Remaining:
              description: Requests left in this second.
              schema:
                type: string
                pattern: ^[0-9]+$
            RateLimit-Reset:
              description: Seconds until the next second opens (0 or 1).
              schema:
                type: string
                pattern: ^[0-9]+$
            Tawked-Daily-Remaining:
              description: E-mails (recipients) left today, a Riyadh day.
              schema:
                type: string
                pattern: ^[0-9]+$
            Idempotent-Replayed:
              description: >-
                Sent as `true` on the answer to a repeated Idempotency-Key;
                absent on a first answer.
              schema:
                type: string
                enum:
                  - 'true'
        '400':
          description: >-
            `service_required`: Partner key used with no `application` (or
            `service`) in the request body.; `invalid_json`: The request body is
            not valid JSON.; `invalid_request`: start: `to` (and `phone`) both
            missing or blank. check: `id` or `code` missing.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Error'
                  - properties:
                      error:
                        enum:
                          - service_required
                          - invalid_json
                          - invalid_request
        '401':
          description: >-
            `unauthorized`: Missing, unknown, revoked, or mode-mismatched key;
            or an unknown/suspended partner.; `key_expired`: The key's
            `expires_at` has passed. Checked right after the key is recognised,
            before the IP allowlist or scope.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Error'
                  - properties:
                      error:
                        enum:
                          - unauthorized
                          - key_expired
        '402':
          description: >-
            `insufficient_credits`: The account's prepaid balance is below what
            the message needs once this month's free e-mails are used. The body
            adds `balance_halalas` and `price_halalas` (the whole halalas it
            needed); nothing was sent or recorded.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Error'
                  - properties:
                      error:
                        enum:
                          - insufficient_credits
        '403':
          description: >-
            `live_key_required`: A test (tk_test_) key on a management endpoint:
            domains, suppressions, metrics and templates are the account's real
            objects, managed with the application's live key, and received
            e-mail is read with it too. A test key sends, reads and cancels
            messages in test mode; a partner's test key (tk_partner_test_) has
            no e-mail at all.; `email_early_access`: Tawked Email is early
            access; apply from the console. The account has not been granted
            access yet: apply from the application's Email area, and Tawked's
            team answers on WhatsApp, in the console and by e-mail.;
            `key_domain_mismatch`: A sending key limited to one domain sent from
            another (the message names the domain), or its domain was removed:
            it sends from that domain alone.; `account_not_active`: The
            application is not approved yet, the account is banned, or a partner
            disabled this application. All four causes share this one response.;
            `ip_not_allowed`: The caller's IP does not match the key's
            `ip_allowlist` (exact IPs and/or CIDR ranges, IPv4 and IPv6).;
            `insufficient_scope`: The key was not granted this call: a custom
            key without this product, or with a level below the call, such as a
            key that checks where the call sends. The response header
            `WWW-Authenticate` names the scope the call needs. Judged right
            after the key is recognised, before `account_not_active` and the
            request's shape. This operation needs `email:send`.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Error'
                  - properties:
                      error:
                        enum:
                          - live_key_required
                          - email_early_access
                          - key_domain_mismatch
                          - account_not_active
                          - ip_not_allowed
                          - insufficient_scope
          headers:
            WWW-Authenticate:
              description: >-
                Sent with `insufficient_scope` only: the scope this operation
                needs, which the key was not granted.
              schema:
                type: string
              example: Bearer error="insufficient_scope", scope="email:send"
        '404':
          description: >-
            `service_not_found`: Partner key, but `application`/`service` does
            not match any of that partner's provisioned applications.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Error'
                  - properties:
                      error:
                        enum:
                          - service_not_found
        '409':
          description: >-
            `idempotency_key_reused`: This `Idempotency-Key` already sent a
            different message (other recipients, subject, body, reply-to,
            headers, tags, time or files), or a different batch, within the last
            24 hours. Nothing was sent; use one key per message.;
            `no_verified_domain`: The application has no verified sender domain
            yet (or does not have Tawked Email). Add one in the application's
            **Email** area and add its one TXT record.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Error'
                  - properties:
                      error:
                        enum:
                          - idempotency_key_reused
                          - no_verified_domain
        '413':
          description: >-
            `request_too_large`: The request body is larger than the server
            accepts, so it never arrived whole. Nothing was recorded or charged;
            keep the attachments within 10 MiB together, and a batch within 10
            MiB.; `message_too_large`: `html` and `text` together are larger
            than 512 KiB.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Error'
                  - properties:
                      error:
                        enum:
                          - request_too_large
                          - message_too_large
        '422':
          description: >-
            Batch invalid / `header_not_allowed`: A header of `headers` is one
            Tawked or the sending service sets (the body's `header` names it),
            or breaks the unsubscribe rules: `List-Unsubscribe` holds
            `<https:…>` or `<mailto:…>` URIs in ASCII, and
            `List-Unsubscribe-Post` is `List-Unsubscribe=One-Click` beside an
            `https:` one. Nothing was sent.; `sender_not_verified`:
            `from.address` is not on a verified domain of this application:
            another domain, a domain still pending, or one whose records are
            gone.; `invalid_destination`: A recipient is not a syntactically
            valid e-mail address. Beyond the original shape, the body adds
            `field` (`to`, `cc` or `bcc`) and `field_index`, its place there.;
            `content_blocked`: The message links to a host on Tawked's list of
            blocked hosts (known phishing or malware). The body adds `host`, the
            host at fault. Nothing was sent or charged; remove the link. In a
            batch, the refused item carries `host`.; `batch_invalid`: An item of
            a batch was refused, so nothing was sent or charged (the default,
            strict validation). `errors` lists each refused item: its `index` in
            the batch, its `error` and `message`, and `field` and `field_index`
            for the value at fault.; `test_mode_recipient`: Test keys send only
            to the simulator addresses: delivered@, bounced@, complained@,
            suppressed@, delayed@, opened@ and clicked@sim.tawked.com (`field`,
            and `field_index` among several).; `template_not_found`: No template
            of the application has this id or alias (`field: "template.id"`).;
            `template_not_published`: The template has never been published:
            publish it, or send its draft with a test key (`"version":
            "draft"`).; `template_variable_missing`: A variable the template
            needs has no value and no fallback (`field:
            "template.variables.<KEY>"`).; `template_variable_unknown`: A
            variable the template does not declare.;
            `template_variable_invalid`: A value that is not a string or a
            number, or longer than 2000 characters.;
            `template_variables_invalid`: `template.variables` is not an object
            (over SMTP: `550 5.7.1 template_variables_invalid`).
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Error'
                  - properties:
                      error:
                        enum:
                          - header_not_allowed
                          - sender_not_verified
                          - invalid_destination
                          - content_blocked
                          - batch_invalid
                          - test_mode_recipient
                          - template_not_found
                          - template_not_published
                          - template_variable_missing
                          - template_variable_unknown
                          - template_variable_invalid
                          - template_variables_invalid
              examples:
                batch_invalid:
                  summary: Batch invalid
                  value:
                    error: batch_invalid
                    message: 'No email was sent: fix the emails listed'
                    errors:
                      - index: 1
                        error: invalid_destination
                        message: '`to[0]` is not a valid e-mail address'
                        field: to
                        field_index: 0
        '429':
          description: >-
            `rate_limited`: The account made its requests for this second: a
            thousandth of its daily limit, never fewer than 10 a second (10 at
            the default), counted for all its applications, keys and the SMTP
            relay together; a batch counts once. Nothing was recorded or
            charged. `Retry-After: 1`; the `RateLimit-*` headers on every send
            say where the account stands. On the domain endpoints: an
            application adds at most ten domains a minute and checks them at
            most six a minute; `Retry-After` says when to try again.;
            `daily_cap_reached`: The account sent its daily limit of e-mails
            (Riyadh time, every recipient counted on the day it is sent): 5,000
            unless Tawked set another for the account. A message whose
            recipients exceed what remains is refused whole; beyond the original
            shape the body adds `remaining`. Nothing was recorded or charged;
            the limit resets at midnight, and the account can ask for a higher
            one from the console.; `test_mode_limit_reached`: Test mode sends at
            most 1000 e-mails a day for an application (Tawked's limit). It
            starts again at midnight, Riyadh time.; `too_many_requests`: Per-key
            rate limit exceeded (default 120 requests/minute, fixed 60s window;
            1,200 on the e-mail endpoints). Checked before authentication. The
            `Retry-After` header gives the seconds to the next window.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Error'
                  - properties:
                      error:
                        enum:
                          - rate_limited
                          - daily_cap_reached
                          - test_mode_limit_reached
                          - too_many_requests
          headers:
            Retry-After:
              description: >-
                Seconds to wait: 1 with `rate_limited` (the account's second),
                the seconds to the next minute with `too_many_requests` (the
                key's minute). `daily_cap_reached` carries none.
              schema:
                type: string
                pattern: ^[0-9]+$
            RateLimit-Limit:
              description: >-
                The account's requests a second on the e-mail routes, for all
                its applications, keys and the SMTP relay together: max(10, its
                daily limit / 1000).
              schema:
                type: string
                pattern: ^[0-9]+$
            RateLimit-Remaining:
              description: Requests left in this second.
              schema:
                type: string
                pattern: ^[0-9]+$
            RateLimit-Reset:
              description: Seconds until the next second opens (0 or 1).
              schema:
                type: string
                pattern: ^[0-9]+$
            Tawked-Daily-Remaining:
              description: E-mails (recipients) left today, a Riyadh day.
              schema:
                type: string
                pattern: ^[0-9]+$
        '500':
          description: >-
            `internal_error`: An unhandled server error. Quote the X-Request-Id
            header if you report it.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Error'
                  - properties:
                      error:
                        enum:
                          - internal_error
        '503':
          description: >-
            `service_unavailable`: Tawked Email is holding every new send for a
            while, a rare platform state. Nothing was recorded or charged; retry
            later.; `email_paused`: Sending is paused for the account: after a
            high bounce or complaint rate, a sudden jump in volume with bounces
            or complaints above Tawked's line, a pause at the sending service,
            or by Tawked's team. Nothing was sent or charged; request a review
            from the console's Email area, or contact support.;
            `email_platform_busy`: Tawked Email has reached today's sending
            capacity across all accounts, a rare state. Nothing was recorded or
            charged; retry after the `Retry-After` header's seconds.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Error'
                  - properties:
                      error:
                        enum:
                          - service_unavailable
                          - email_paused
                          - email_platform_busy
          headers:
            Retry-After:
              description: 'Sent with `email_platform_busy`: seconds to wait (600).'
              schema:
                type: string
                pattern: ^[0-9]+$
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |-
            curl -X POST https://tawked.com/v1/email/messages/batch \
              -H "Authorization: Bearer tk_live_xxxxxxxxxxxxxxxxxxxx" \
              -H "Content-Type: application/json" \
              -H "Idempotency-Key: orders-2026-10-21-0900" \
              -d '[
                {
                    "from": "متجر أكمي <orders@acme.sa>",
                    "to": [
                        "sara@example.com"
                    ],
                    "subject": "طلبك رقم 1042 قيد التجهيز",
                    "html": "<p>استلمنا طلبك رقم 1042.</p>",
                    "reference": "order-1042",
                    "tags": [
                        {
                            "name": "category",
                            "value": "order"
                        }
                    ]
                },
                {
                    "from": "متجر أكمي <orders@acme.sa>",
                    "to": [
                        "ali@example.com"
                    ],
                    "subject": "طلبك رقم 1043 قيد التجهيز",
                    "html": "<p>استلمنا طلبك رقم 1043.</p>",
                    "reference": "order-1043",
                    "tags": [
                        {
                            "name": "category",
                            "value": "order"
                        }
                    ]
                }
            ]'
        - lang: javascript
          label: Node.js
          source: >-
            const res = await
            fetch("https://tawked.com/v1/email/messages/batch", {
              method: "POST",
              headers: {
                Authorization: "Bearer tk_live_xxxxxxxxxxxxxxxxxxxx",
                "Content-Type": "application/json",
                "Idempotency-Key": "orders-2026-10-21-0900",
              },
              body: JSON.stringify([
                  {
                      "from": "متجر أكمي <orders@acme.sa>",
                      "to": [
                          "sara@example.com"
                      ],
                      "subject": "طلبك رقم 1042 قيد التجهيز",
                      "html": "<p>استلمنا طلبك رقم 1042.</p>",
                      "reference": "order-1042",
                      "tags": [
                          {
                              "name": "category",
                              "value": "order"
                          }
                      ]
                  },
                  {
                      "from": "متجر أكمي <orders@acme.sa>",
                      "to": [
                          "ali@example.com"
                      ],
                      "subject": "طلبك رقم 1043 قيد التجهيز",
                      "html": "<p>استلمنا طلبك رقم 1043.</p>",
                      "reference": "order-1043",
                      "tags": [
                          {
                              "name": "category",
                              "value": "order"
                          }
                      ]
                  }
              ]),
            });

            const data = await res.json();
        - lang: python
          label: Python
          source: |-
            import requests

            res = requests.post(
                "https://tawked.com/v1/email/messages/batch",
                headers={"Authorization": "Bearer tk_live_xxxxxxxxxxxxxxxxxxxx", "Idempotency-Key": "orders-2026-10-21-0900"},
                json=[
                    {
                        "from": "متجر أكمي <orders@acme.sa>",
                        "to": [
                            "sara@example.com"
                        ],
                        "subject": "طلبك رقم 1042 قيد التجهيز",
                        "html": "<p>استلمنا طلبك رقم 1042.</p>",
                        "reference": "order-1042",
                        "tags": [
                            {
                                "name": "category",
                                "value": "order"
                            }
                        ]
                    },
                    {
                        "from": "متجر أكمي <orders@acme.sa>",
                        "to": [
                            "ali@example.com"
                        ],
                        "subject": "طلبك رقم 1043 قيد التجهيز",
                        "html": "<p>استلمنا طلبك رقم 1043.</p>",
                        "reference": "order-1043",
                        "tags": [
                            {
                                "name": "category",
                                "value": "order"
                            }
                        ]
                    }
                ],
            )
            data = res.json()
components:
  schemas:
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: A stable machine-readable code; the docs list every one.
      additionalProperties: true
  securitySchemes:
    bearerKey:
      type: http
      scheme: bearer
      description: >-
        Authorization: Bearer <api key>. An application key (tk_live_, tk_test_)
        has full access, which covers every product and any product added later,
        or custom access, chosen when the key is created: one or more of the
        scopes `verify:check`, `verify:send` (includes `verify:check`),
        `notifications:read`, `notifications:send` (includes
        `notifications:read`), `email:read`, `email:send` (includes
        `email:read`), `email:manage` (includes `email:send`),
        `webhooks:manage`, `email:inbound`, `notifications:templates` (includes
        `notifications:read`), `chat:menus`, `chat:attendant`. No key made on
        the API keys page holds `notifications:templates`, full access included:
        the three template writes answer such a key 403 `insufficient_scope`. A
        connected app's key holds it. Nor `chat:menus`: the five conversation
        menu operations answer such a key 403 `insufficient_scope`, and a
        connected app's key holds it once the client approved it. Nor
        `chat:attendant`: the five auto-attendant operations answer such a key
        403 `insufficient_scope` too, and a connected app's key holds it once
        the client approved it. `email:manage` and `webhooks:manage` are held
        only by a key someone chose them for: a full-access key, old or new,
        never holds them. `email:inbound`, which reads, deletes and forwards
        received e-mail, is opt-in on every key, full access included: a key
        holds it only when it was turned on when the key was created. A call
        outside the key's access answers 403 `insufficient_scope` and names the
        scope it needs in the `WWW-Authenticate` response header. A partner key
        (tk_partner_) always has full access. Whatever its access, a key is a
        server-side secret.
    headerKey:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        The same API key, with the same access, as a header, for clients that
        cannot set Authorization.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.