> ## 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.

# Get an email

> Reads a message's current status and timestamps. `error` is set when the message bounced or failed. A message belongs to the key's application; any other id answers `404`.

Guide: [Sending email](/email/messages)


## OpenAPI

````yaml https://tawked.com/openapi.json get /v1/email/messages/{id}
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. 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 one transactional message per call from an address on a
      verified domain of the application, and read its status. Live keys only.
  - 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/{id}:
    get:
      tags:
        - Email
      summary: Get an email
      description: >-
        Reads a message's current status and timestamps. `error` is set when the
        message bounced or failed. A message belongs to the key's application;
        any other id answers `404`.
      operationId: email_message
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Delivered / Bounced
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  status:
                    type: string
                  from:
                    type: object
                    properties:
                      name:
                        type: string
                      address:
                        type: string
                  to:
                    type: string
                  subject:
                    type: string
                  reference:
                    type: string
                  price_halalas:
                    type: integer
                  created_at:
                    type: string
                    format: date-time
                  error:
                    type:
                      - object
                      - 'null'
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                  sent_at:
                    type: string
                    format: date-time
                  delivered_at:
                    type:
                      - string
                      - 'null'
                    format: date-time
                  bounced_at:
                    type:
                      - string
                      - 'null'
                    format: date-time
                  complained_at:
                    type:
                      - string
                      - 'null'
                  failed_at:
                    type:
                      - string
                      - 'null'
              examples:
                delivered:
                  summary: Delivered
                  value:
                    id: 3d9a7f2e-1c4b-4e8a-9f6d-2b5c8e1a7d40
                    status: delivered
                    from:
                      name: متجر أكمي
                      address: orders@acme.sa
                    to: customer@example.com
                    subject: طلبك رقم 1042 قيد التجهيز
                    reference: order-1042
                    price_halalas: 1
                    created_at: '2026-10-09T12:00:00+03:00'
                    error: null
                    sent_at: '2026-10-09T12:00:01+03:00'
                    delivered_at: '2026-10-09T12:00:03+03:00'
                    bounced_at: null
                    complained_at: null
                    failed_at: null
                bounced:
                  summary: Bounced
                  value:
                    id: 3d9a7f2e-1c4b-4e8a-9f6d-2b5c8e1a7d40
                    status: bounced
                    from:
                      name: متجر أكمي
                      address: orders@acme.sa
                    to: customer@example.com
                    subject: طلبك رقم 1042 قيد التجهيز
                    reference: order-1042
                    price_halalas: 1
                    created_at: '2026-10-09T12:00:00+03:00'
                    error:
                      code: bounced
                      message: smtp; 550 5.1.1 user unknown
                    sent_at: '2026-10-09T12:00:01+03:00'
                    delivered_at: null
                    bounced_at: '2026-10-09T12:00:03+03:00'
                    complained_at: null
                    failed_at: null
        '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
        '403':
          description: >-
            `live_key_required`: A test (tk_test_) key. There is no e-mail
            sandbox; use the application's live key.; `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:read`.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Error'
                  - properties:
                      error:
                        enum:
                          - live_key_required
                          - 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:read"
        '404':
          description: >-
            Unknown id / `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
                          - not_found
              examples:
                unknown_id:
                  summary: Unknown id
                  value:
                    error: not_found
        '429':
          description: >-
            `too_many_requests`: Per-key rate limit exceeded (default 120
            requests/minute, fixed 60s window). Checked before authentication.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Error'
                  - properties:
                      error:
                        enum:
                          - too_many_requests
        '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
      x-codeSamples:
        - lang: bash
          label: cURL
          source: >-
            curl
            https://tawked.com/v1/email/messages/3d9a7f2e-1c4b-4e8a-9f6d-2b5c8e1a7d40
            \
              -H "Authorization: Bearer tk_live_xxxxxxxxxxxxxxxxxxxx"
        - lang: javascript
          label: Node.js
          source: >-
            const res = await
            fetch("https://tawked.com/v1/email/messages/3d9a7f2e-1c4b-4e8a-9f6d-2b5c8e1a7d40",
            {
              headers: {
                Authorization: "Bearer tk_live_xxxxxxxxxxxxxxxxxxxx",
              },
            });

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

            res = requests.get(
                "https://tawked.com/v1/email/messages/3d9a7f2e-1c4b-4e8a-9f6d-2b5c8e1a7d40",
                headers={"Authorization": "Bearer tk_live_xxxxxxxxxxxxxxxxxxxx"},
            )
            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`), `notifications:templates` (includes
        `notifications:read`). 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. 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.