Opt-out, consent & TCPA

Honouring opt-out is a legal obligation, not a feature. TextKit enforces it on your behalf for every send, keeps an append-only consent ledger you can export, and gives you the events to keep your own systems in sync. There is nothing to configure; every account gets this by default.

Revocation in plain English

The FCC's April 2025 revocation rule requires honouring a revocation expressed by any reasonable means, not just the standard keywords. TextKit detects revocation in three tiers, in order:

All three record the opt-out, send the single confirmation reply, block future sends, and emit message.opted_out with a method field (keyword, phrase, or ai) so you can see how it was detected. A revocation is never answered by an auto-reply.

Keywords

A second STOP from a number that is already opted out changes nothing: no second confirmation, no second event.

Replies speak for your business

The confirmation, resubscribe and help replies name you, not TextKit, because the person texting has never heard of us:

• A number linked to a registration sends exactly the HELP, STOP and opt-in messages that registration filed with the carriers, including your support contact.
• A number assigned to a customer is answered in that customer's name.
• Otherwise the reply uses your account name. An account name that is an email address is never shown; the reply says "this number" instead.

Keyword matching is exact: the message has to be the keyword, ignoring case, surrounding whitespace and punctuation. "please stop by tomorrow" is an ordinary message; the phrase tier only fires on messaging-directed forms like "stop texting me".

One suppression list per account

Every account has a single suppression list, and every ordinary message passes through it before it can reach a carrier. It is account-wide on purpose: an opt-out applies to all your numbers, sender pools and customers, so a recipient who texts STOP to one of your numbers cannot be texted from another.

The list fails closed. If we cannot read it, the send is not attempted: you get 503 with Retry-After, nothing is sent and nothing is billed. We would rather make you retry than text someone who said stop.

You manage the same list through the API above: read it (GET /v1/consent), add to it (POST /v1/consent/{phone}, or /v1/consent/import for a list from another provider) and export it (/v1/consent/export).

An opt-out the person gave themselves (a STOP or plain-words reply, or one imported from another provider) is permanent: only they can lift it, by texting START (or your opt-in keyword) to one of your numbers. POST /v1/consent/{phone} with "status": "opted_in" answers 409 invalid_request and changes nothing. Recording an opt-out of your own over theirs keeps theirs.

An opt-out you recorded yourself (POST /v1/consent/{phone} or the console), or one from a report through our form (we cannot confirm who filed it), can be undone with proof of a new opt-in, collected_at at or after the opt-out; otherwise 409 invalid_request (param: proof or proof.collected_at). Once the person texts STOP themselves, it is theirs and permanent. In the console, only an admin can (Compliance, Opt back in).

The list is yours alone. An opt-out silences your traffic to that number, not everyone's. Someone who unsubscribes from one sender does not stop receiving login codes from another; that would turn an unsubscribe into an account lockout.

What gets blocked

POST /v1/messages to an opted-out number returns:

{
  "error": {
    "code": "recipient_opted_out",
    "message": "This recipient opted out of your messages on Oct 5, 2026 at 8:42 AM UTC by replying STOP. Nothing was sent and you were not charged. They can opt back in by texting START to your number.",
    "param": "to",
    "opted_out_at": "2026-10-05T08:42:00.000Z",
    "opted_out_via": "sms_keyword",
    "opted_out_method": "keyword",
    "failure": { "code": "opted_out", "title": "Recipient opted out", "explanation": "...", "action": "Recommended: ..." }
  }
}

The status is 403. Nothing leaves our network and nothing is billed. You do not have to check consent before sending: send, and handle this one code.

A refused send also leaves a trace, so "why wasn't this delivered?" is answered wherever you look:

• a message.blocked event (and webhook) with to, from, reason: "opted_out" and the same opted_out_* fields;
• a blocked_send entry in the number's consent history (at most one a day per number, so a retry loop cannot bury the opt-out itself);
• blocked_sends and last_blocked_at on GET /v1/consent/{phone}.

Broadcast recipients who opted out are skipped and counted, never messaged. Scheduled sends re-check consent at send time.

One-time codes are blocked too. POST /v1/verify to a number that opted out answers 403 recipient_opted_out: nothing is sent and nothing is billed. The same applies when the person texted STOP to the number the code would come from. They text START to get codes again.

The consent ledger

Every consent change is appended to a per-number history that is never deleted: opt-outs (with the detected text and method), opt-ins, imports, API changes, and blocked sends. That history is your TCPA audit trail.

# Current state + full history for one number
curl https://api.jointextkit.com/v1/consent/+14155550132 \
  -H "Authorization: Bearer $TEXTKIT_API_KEY"

# Set consent from your own system (CRM sync, web form, support tool)
curl -X POST https://api.jointextkit.com/v1/consent/+14155550132 \
  -H "Authorization: Bearer $TEXTKIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "opted_out", "note": "revoked by email"}'

# The whole suppression list, paginated
curl "https://api.jointextkit.com/v1/consent?limit=100" \
  -H "Authorization: Bearer $TEXTKIT_API_KEY"

# Bulk import (up to 500 per request), e.g. when migrating from another provider
curl -X POST https://api.jointextkit.com/v1/consent/import \
  -H "Authorization: Bearer $TEXTKIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone_numbers": ["+14155550132", "+16155550176"]}'

# Export everything as CSV
curl https://api.jointextkit.com/v1/consent/export \
  -H "Authorization: Bearer $TEXTKIT_API_KEY"

Opt-ins set via the API can carry proof: the source, time, page, exact disclosure wording, IP and user agent (see Opt-in proof), and campaign_id, the registration the person opted in to. /v1/consent/export?type=ledger exports every consent event with those proof columns.

# An opt-in for one registration, with the evidence a marketing registration requires
curl -X POST https://api.jointextkit.com/v1/consent/+14155550132 \
  -H "Authorization: Bearer $TEXTKIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "opted_in", "campaign_id": "reg_a1B2c3D4e5F6",
       "proof": {"source": "web_form", "collected_at": "2026-10-01T15:04:05Z",
                 "page_url": "https://acme.example/texts",
                 "disclosure": "By checking this box you agree to receive marketing texts from Acme..."}}'

Consent is per registration

Carriers treat consent as given to one business for one kind of message: the registration (use case) your number sends under. Someone who agreed to appointment reminders did not agree to promotions from the same business. So the consent API records an opt-in either for the whole account or for one registration, and the send check reads it like this:

An opt-out is never narrower than the account: STOP to any of your numbers stops every registration, and clears every opt-in the number had. A keyword opt-in is scoped automatically to the registration of the number the person texted, with the inbound message recorded as its proof.

GET /v1/consent/{phone} lists the registrations a number is opted in to as campaigns, and each history entry carries its campaign_id. Existing account-level opt-ins keep working for every transactional send and for marketing from an unregistered number; only marketing from a registered number now asks for the registration-scoped record.

Proof for marketing opt-ins

An opt-in recorded for a registration whose use case is marketing (or mixed) must carry proof: the source, collected_at, and the page_url for a web form or the inbound message_id for a keyword. Without it POST /v1/consent/{phone} answers 400 invalid_request and records nothing; a contact import skips the row with the reason. Opt-ins for other registrations, and account-level opt-ins, accept the same fields and do not insist on them. Keyword opt-ins (START, JOIN, YES) and hosted opt-in page sign-ups record their proof by themselves.

Re-confirmation after 30 days

Some carriers require a fresh YES from anyone a marketing program has not texted in 30 days. We do that for you: see re-confirmation.

The console Compliance page shows the same ledger with search, per-number history, import and export.

Topics are narrower than an opt-out

Subscription topics let a person stop one kind of message (say Marketing) and keep another. They sit on top of everything on this page and never replace it: the opt-out check runs first on every send, an opted-out number gets nothing whatever its topics say, and subscribing a number to a topic does not opt it back in. Topic changes appear in the ledger as topic_unsubscribe and topic_subscribe; opt-in evidence stored by a contact import appears as import. Neither changes status.

Events

Subscribe to these and mirror the state in your own database. You should never re-add a number that opted out, even though we block it. Imports do not emit per-number events; the ledger records each one.

Testing it

Opt-out works in the sandbox exactly as it does live, scoped to your account, so you can rehearse the whole path before going live. The phrase tier is deterministic, so it is testable too:

curl -X POST https://api.jointextkit.com/v1/test/inbound \
  -H "Authorization: Bearer $TEXTKIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from":"+15005550006","body":"please stop texting me"}'

The next send to that number returns 403, and GET /v1/consent/+15005550006 shows the opt-out with "method": "phrase". Send START to opt back in; the history keeps both entries.

This page is educational, not legal advice. Your own counsel decides what your consent program needs; TextKit gives you enforcement and records by default.

Bring your opt-outs

A number that is new to your TextKit account is not safe to text just because nobody has replied STOP here yet. If you texted these people from another provider or tool, some of them opted out there, and that choice still applies. Opt-out lists are not shared between providers, so the list has to come with you.

1. Export the opt-out list from wherever you sent before. Any file with one phone number per row works: a single column with or without a header, or an export with other columns beside it. Numbers can be +14155550123, 14155550123, (415) 555-0123 or 415-555-0123.
2. Upload it in Console → Numbers → Bring your numbers → Bring your opt-outs, or send it to the API:

curl https://api.jointextkit.com/v1/consent/import \
  -H "Authorization: Bearer $TEXTKIT_API_KEY" -H "Content-Type: application/json" \
  -d '{"phone_numbers": ["+14155550123", "(212) 555-0148"]}'

Up to 500 numbers per request. Each one is recorded as opted out with the method import and is refused on every send from then on (403 recipient_opted_out). The console shows how many were imported and how many were skipped, with the reason: not a US or Canada number, a blank row, repeated in the file, or already on your list.

In a migration this step is required. The import of numbers, pools and webhooks does not run until you have uploaded a list or confirmed, in the console, "I have no existing opt-outs to carry over". That confirmation is recorded in your audit log as migration.opt_outs_attested.

Outside a migration you will see a reminder, not a block, when you import contacts or send a first broadcast with no opt-outs on file.