---
title: "Add Unsubscribes (V2)"
method: POST
path: "/v2/sms/unsubscribes"
tags: ["SMS Unsubscribes"]
---

# Add Unsubscribes (V2)

`POST /v2/sms/unsubscribes`

Upserts one or more customer unsubscribe records. Valid entries are
persisted with `consent = false` (unsubscribed). Invalid mobile numbers
are skipped; see response codes for partial-success behavior.

## Request body

- SmsUnsubscribeEntry[] — JSON array of customer unsubscribe entries. Maximum 250 entries per request.
  - `customerId` string, required — Unique customer identifier within the tenant/app.
  - `mobileNumber` string, required — Mobile number validated against `^\+?[1-9]\d{3,14}$` (optional leading `+`, first digit 1–9, 4–15 digits total). Invalid numbers are rejected with the E.164 error responses below.
  - `timestamp` string, date-time — Optional event timestamp (RFC 3339, e.g. `2020-06-09T05:32:21Z`). The API also accepts other date strings parseable by Laravel, such as `2020-06-09 05:32:21`. If omitted, the server uses the current time. Updates are only applied when this value is newer than the existing record's `updated_at`.

## Response `201`

All entries processed successfully

- SuccessResponse
  - `message` string

## Other responses

- `207` — Partial success — one or more entries had invalid mobile numbers. Valid entries were still processed.
- `400` — Bad request — empty body (`[]`), no valid data, or every mobile number failed E.164 validation.
- `401` — Authentication required or invalid
- `422` — Request validation failed (422)
- `429` — Rate limit exceeded. Limited to 6000 requests per minute per Authorization header.

---

[API](https://skmtc.net/optimove/apis/optimove-api.md) · [All operations](https://skmtc.net/optimove/apis/optimove-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/optimove/optimove-api/revisions/fc55c5b1bec5/schema)