> ## 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. # Suppress addresses > Adds up to 1000 addresses to the account's list (Tawked's limit): no application of the account sends to them until they are lifted. Answers how many were added, how many were there already, and which were not addresses, by their place in the list. A live key of the application with the explicit `email:manage`: a full-access key does not hold it. Guide: [Suppressed addresses](https://docs.tawked.com/email/suppressions.md) ## OpenAPI ````yaml https://tawked.com/openapi.json post /v1/email/suppressions 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/suppressions: post: tags: - Email summary: Suppress addresses description: >- Adds up to 1000 addresses to the account's list (Tawked's limit): no application of the account sends to them until they are lifted. Answers how many were added, how many were there already, and which were not addresses, by their place in the list. A live key of the application with the explicit `email:manage`: a full-access key does not hold it. operationId: email_suppressions_add parameters: - name: Idempotency-Key in: header required: false description: >- Up to 128 characters. A retry with the same key and the same body within 24 hours answers what the first call answered and changes nothing again; the same key with another body answers `409 idempotency_key_reused`. schema: type: string requestBody: required: true content: application/json: schema: type: object properties: addresses: type: array description: 1 to 1000 addresses. Or `address`, one. address: type: string description: One address, in place of `addresses`. responses: '201': description: Added content: application/json: schema: type: object properties: added: type: integer existing: type: integer invalid: type: array items: type: object properties: index: type: integer code: type: string examples: added: summary: Added value: added: 2 existing: 1 invalid: - index: 3 code: invalid_address '400': description: >- `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: - 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: >- No email:manage / `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.; `application_key_required`: A partner key. Use the application's own key: partner keys manage client applications through the Partner API.; `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:manage`. content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - properties: error: enum: - live_key_required - application_key_required - account_not_active - ip_not_allowed - insufficient_scope examples: no_email_manage: summary: No email:manage value: error: 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:manage" '409': description: >- `email_access_required`: The account has not asked for Email yet: ask from the application's Email area in the console.; `email_access_pending`: The account's request for Email waits for Tawked's team.; `email_product_off`: The application's Email product is off: turn it on in the console. content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - properties: error: enum: - email_access_required - email_access_pending - email_product_off '422': description: >- No valid address / `suppression_invalid_addresses`: No address given is valid, or `addresses` is not a list.; `suppression_too_many`: More than 1000 addresses in one call (Tawked's limit). content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - properties: error: enum: - suppression_invalid_addresses - suppression_too_many examples: no_valid_address: summary: No valid address value: error: suppression_invalid_addresses message: No address given is valid field: addresses '429': description: >- `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: - 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 -X POST https://tawked.com/v1/email/suppressions \ -H "Authorization: Bearer tk_live_xxxxxxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "addresses": [ "sara@example.com", "omar@example.com" ] }' - lang: javascript label: Node.js source: >- const res = await fetch("https://tawked.com/v1/email/suppressions", { method: "POST", headers: { Authorization: "Bearer tk_live_xxxxxxxxxxxxxxxxxxxx", "Content-Type": "application/json", }, body: JSON.stringify({ "addresses": [ "sara@example.com", "omar@example.com" ] }), }); const data = await res.json(); - lang: python label: Python source: |- import requests res = requests.post( "https://tawked.com/v1/email/suppressions", headers={"Authorization": "Bearer tk_live_xxxxxxxxxxxxxxxxxxxx"}, json={ "addresses": [ "sara@example.com", "omar@example.com" ] }, ) 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.