--- title: "Create an SMS suppression" method: POST path: "/v1/sms/suppressions" tags: ["sms-suppressions"] --- # Create an SMS suppression `POST /v1/sms/suppressions` ## Request - Base URL: `https://us1.platform.bird.com` - URL: `https://us1.platform.bird.com/v1/sms/suppressions` - Auth: one of: - HTTP bearer - API key in cookie `bird_session` Stops a sender's messages to a subscriber, with reason `manual`, blocking every category including transactional. Both ends are required: a suppression covers a sender-and-subscriber pair, so stopping all of your senders means one call per sender. Adding is idempotent. A `201` means a new suppression was recorded, and a `200` means a `manual` one for that pair was already in place and is returned unchanged. A pair already stopped for another reason, such as the subscriber having texted a stop keyword, still gets its own `manual` record, and messages stay stopped until every one of them has ended. ## Headers - `Idempotency-Key` string - `X-Workspace-Id` string - `X-Organization-Id` string ## Request body - SMSSuppressionCreate: Stops one sender's messages to one subscriber. Both ends are required, because a suppression covers a sender-and-subscriber pair rather than a subscriber alone. - `destination` string, required: The subscriber to stop messaging, in E.164 format. - `originator` string, required: The sender to stop. Your other senders keep reaching this subscriber, so stopping every one of them means one call per sender. ## Response `200` A manual suppression for this pair was already in place. The existing one is returned. - SMSSuppression: One period during which a sender's messages to a subscriber are stopped: when it started, what started it, and what ended it. A subscriber who opts out, opts back in, and opts out again has three of these on record rather than one current state, and each keeps its own dates once it ends. The list returns the periods in force; fetch one by ID to read an ended one. - `id` string, required - `destination` string, required: The subscriber, in E.164 format. - `originator` string, required: The sender this stops. A suppression covers one sender, so your other senders still reach this subscriber. Opting out of one of your programs does not opt out of the others. - `reason` string, required: Reason this sender cannot message the subscriber: - `keyword_stop`: The subscriber sent a stop keyword. A start keyword clears it. - `carrier_opted_out`: The carrier reported the opt-out. - `manual`: Your workspace added the suppression through the API or dashboard. This is an open enum. Accept unrecognized values. - `origin` string, required: How the opt-out reached us: - `keyword`: an inbound message from the subscriber. - `dlr_event`: a carrier delivery report. - `api_key`: an API call. - `user`: someone acting in the dashboard. Kept beside the reason because one reason can arrive by more than one route. This list grows over time, so treat an unknown value as informational rather than rejecting the record. - `applies_to` string, required: Message categories blocked for this sender and subscriber. `all` blocks every category, including authentication and transactional messages. `non_transactional` blocks marketing messages only. Responses currently use `all`. Treat unrecognized values as blocking every category. - `blocking` boolean, required: Whether this is stopping messages right now. Always true in a list, which carries only the suppressions in force; false when you fetch one by ID that has since ended, which is also when `ended_at` is set. - `source_sms_id` string - `effective_at` string, date-time, required: When the subscriber opted out, as reported by whoever reported it. This is what orders one subscriber's history, and it can be earlier than `created_at` when a message reached us late. - `ended_at` string, date-time, nullable: When this stopped applying. Null while it is still stopping messages. - `ended_reason` string: What ended it: - `keyword_start`: the subscriber texting a start keyword to the same sender. - `api_key`: an API call. - `user`: someone acting in the dashboard. - `carrier_cleared`: the carrier reporting its own opt-out cleared. This list grows over time, so treat an unknown value as informational rather than rejecting the record. - `ended_effective_at` string, date-time, nullable: When the subscriber opted back in, as reported. Null while it is still stopping messages. - `source_end_sms_id` string - `created_at` string, date-time, required: When we recorded it. - `last_asserted_at` string, date-time, required: When we last recorded the subscriber opting out of this sender. Later than `created_at` when they texted a stop keyword again while already suppressed, which adds no new record but does earn another confirmation reply. ## Other responses - `201`: Suppression recorded. - `400`: Bad request - `401`: Authentication required - `403`: Insufficient permissions - `404`: Resource not found - `422`: The request has invalid field values, violates a business rule, or carries a query parameter the endpoint does not declare. Field validation errors use `type: validation_error` and include the affected fields in `details`. Business-rule errors identify the failed rule in `type`. - `429`: Rate limit exceeded - `500`: Internal server error - `503`: The service is temporarily unavailable. If `Retry-After` is present, wait for that delay before retrying; otherwise, retry with exponential backoff. Reuse the same idempotency key and request when retrying a mutation. --- [API](https://skmtc.dev/messagebird/apis/bird-api.md) · [All operations](https://skmtc.dev/messagebird/apis/bird-api/llms.txt) · [OpenAPI document](https://skmtc.dev/messagebird/apis/bird-api/revisions/6dfce1179799?raw)