> ## 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. # Forward a received email > Sends the received e-mail on as a new e-mail from your verified domain: its subject, bodies and attachments, `reply_to` its sender, your note above it. It is a send like any other, charged at the send's price and answered with the same `202`. Needs `email:inbound` and `email:send`. Never more than 10 attachments and 10 MiB; an attachment that could run a program is never forwarded. Guide: [Receiving email](https://docs.tawked.com/email/receiving.md) ## OpenAPI ````yaml https://tawked.com/openapi.json post /v1/email/received/{id}/forward 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/received/{id}/forward: post: tags: - Email summary: Forward a received email description: >- Sends the received e-mail on as a new e-mail from your verified domain: its subject, bodies and attachments, `reply_to` its sender, your note above it. It is a send like any other, charged at the send's price and answered with the same `202`. Needs `email:inbound` and `email:send`. Never more than 10 attachments and 10 MiB; an attachment that could run a program is never forwarded. operationId: email_received_forward parameters: - name: id in: path required: true schema: type: string format: uuid - name: Idempotency-Key in: header required: false description: 'As on a send: the same key answers the first forward again.' schema: type: string requestBody: required: true content: application/json: schema: type: object properties: to: type: string description: 1 to 10 addresses (one may be a string). from: type: object description: >- An address on a verified domain of the application, or `{name, address}`. By default the address's forward-from on its domain, else the first verified domain's default sender. note: type: string description: >- At most 2000 characters, placed as one paragraph above the original. required: - to responses: '202': description: Forwarded 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: 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 subject: type: string reference: type: - string - 'null' tags: type: array items: type: - string - 'null' 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 examples: forwarded: summary: Forwarded value: id: 0199f3b4-2c1d-7e5f-8a9b-0c1d2e3f4a5b status: accepted from: name: متجر أكمي address: orders@acme.sa to: - ops@acme.sa cc: [] bcc: [] reply_to: - sara@example.com subject: استفسار عن الطلب 1042 reference: null tags: [] scheduled_at: null recipients: - id: 0199f3b4-2c1e-7a10-8b2c-3d4e5f6a7b8c address: ops@acme.sa name: null type: to status: queued price_halalas: 0 cost: emails: 1 suppressed: 0 free: 1 billed: 0 halalas: '0' created_at: '2026-10-26T12:20:00+03:00' mode: live '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.; `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:inbound`. content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - properties: error: enum: - live_key_required - email_early_access - 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:inbound" '404': description: >- `service_not_found`: Partner key, but `application`/`service` does not match any of that partner's provisioned applications.; `not_found`: No received e-mail of this application has that id: another application's, one you deleted, one past the 30 days, or an attachment of another e-mail. A partner's key, which receives no e-mail, gets it on every received e-mail call. content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - properties: error: enum: - service_not_found - not_found '409': description: >- Still being read / `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.; `idempotency_in_progress`: A send with this `Idempotency-Key` is still on its way. Nothing was sent again; retry in a moment with the same key: the answer is then the first send's, or a fresh send if the first failed and released the key.; `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.; `received_not_ready`: The received e-mail is still being read (`status` `received`). Forward it once it is `ready`, a few seconds later. content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - properties: error: enum: - idempotency_key_reused - idempotency_in_progress - no_verified_domain - received_not_ready examples: still_being_read: summary: Still being read value: error: received_not_ready message: >- The received email is still being read; forward it once its status is ready. '410': description: >- `received_content_gone`: The stored copy behind the raw message, the attachment or the bodies is gone, so it cannot be downloaded or forwarded. The e-mail's details stay readable. content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - properties: error: enum: - received_content_gone '413': description: >- Too large / `message_too_large`: `html` and `text` together are larger than 512 KiB.; `forward_too_large`: A forward carries at most 10 attachments and 10 MiB in all, a Tawked limit. Download the files and send them yourself. content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - properties: error: enum: - message_too_large - forward_too_large examples: too_large: summary: Too large value: error: forward_too_large message: >- A forward carries at most 10 attachments and 10 MiB in all (a Tawked limit). '422': description: >- A risky attachment / `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`.; `forward_risky_attachment`: The e-mail carries an attachment that could run a program (`risky`); it is never forwarded. content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - properties: error: enum: - sender_not_verified - invalid_destination - content_blocked - forward_risky_attachment examples: a_risky_attachment: summary: A risky attachment value: error: forward_risky_attachment message: >- The email carries an attachment that could run a program; it is never forwarded. '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.; `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 - 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 '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 x-codeSamples: - lang: bash label: cURL source: >- curl -X POST https://tawked.com/v1/email/received/0199f3a1-5c2e-7d40-9a1b-2c3d4e5f6a7b/forward \ -H "Authorization: Bearer tk_live_xxxxxxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "to": "ops@acme.sa", "from": "orders@acme.sa", "note": "للمتابعة" }' - lang: javascript label: Node.js source: >- const res = await fetch("https://tawked.com/v1/email/received/0199f3a1-5c2e-7d40-9a1b-2c3d4e5f6a7b/forward", { method: "POST", headers: { Authorization: "Bearer tk_live_xxxxxxxxxxxxxxxxxxxx", "Content-Type": "application/json", }, body: JSON.stringify({ to: "ops@acme.sa", from: "orders@acme.sa", note: "للمتابعة" }), }); const data = await res.json(); - lang: python label: Python source: |- import requests res = requests.post( "https://tawked.com/v1/email/received/0199f3a1-5c2e-7d40-9a1b-2c3d4e5f6a7b/forward", headers={"Authorization": "Bearer tk_live_xxxxxxxxxxxxxxxxxxxx"}, json={"to": "ops@acme.sa", "from": "orders@acme.sa", "note": "للمتابعة"}, ) 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 . 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.