Compliance checks

Every message you send, through the API, the console, a broadcast, a scheduled send, a recurring schedule or an automation, goes through the same checks in the same order before it reaches a carrier. You call POST /v1/messages; the checks are on by default.

A send that fails a check is blocked: it is not sent, it is not charged, the API says why, and the attempt is in your log with the reason.

+14155550123   Blocked   Quiet hours
+12125550148   Blocked   Previously opted out
+13125550190   Delivered

The checks, in order

The first check that fails is the one you hear about.

After the last check the message goes to the carrier. What a carrier does with it afterwards (filtering, an unreachable phone) is a delivery failure, not a block.

This table is generated from the list the send pipeline is tested against, so it cannot fall out of step with the code.

What a blocked send looks like

The request answers with the status and code in the table, and a failure object you can show to a person:

{
  "error": {
    "code": "quiet_hours",
    "message": "It is 10:41pm for this recipient (America/New_York, from the number's area code). Messages are sent between 8:00am and 9:00pm in the recipient's local time, so this one was not sent and nothing was charged. ...",
    "param": "to",
    "recipient_local_time": "22:41",
    "timezone": "America/New_York",
    "send_after": "2026-10-06T12:00:00.000Z",
    "category": "marketing",
    "category_basis": "request",
    "message_id": "msg_8Fq2ZkT0aLw4nXcV",
    "failure": { "code": "quiet_hours", "title": "Held back for quiet hours", "explanation": "...", "action": "Recommended: ...", "carrier_code": null },
    "request_id": "req_8Fq2ZkT0aLw4nXcV7pHs"
  }
}

The attempt is stored as a message with status: "blocked" and the same failure. Its price is 0, it counts toward no allowance or limit, and it is not part of the conversation with that number.

• Console. Logs shows the status Blocked and the reason. Filter by Blocked, then by reason. Compliance shows blocked sends for the last 7 and 30 days, by reason.
• API. GET /v1/messages?status=blocked lists them; &blocked_reason=quiet_hours narrows to one reason. failure_code matches failed and blocked messages alike.
• Webhook. message.blocked, with reason, message_id and failure.
• Export. The messages CSV has reason_code and reason columns.

Two refusals a looping client can repeat without end (the per-recipient rate and the message allowance) stop adding rows after 500 an hour per account. They are still refused and still counted.

Reason labels

The label is what Logs and the CSV show for each code.

Quiet hours

Every message is sent between 8:00am and 9:00pm in the recipient's local time, and 8:00am to 8:00pm to numbers with a Florida, Maryland or Oklahoma area code. That is the federal calling-time window for telephone solicitations and those states' narrower one, and we apply it to all traffic, not only marketing. A message outside it is held until 8:00am, or refused if it is a single marketing send. This cannot be turned off.

Sent at any hour: one-time codes (judged by the message's wording, not its category), a reply to someone who texted that number in the last 4 hours, the "Reply YES to confirm" text a hosted opt-in page sends right after someone signs up, and sends to your own verified test numbers.

Which messages are marketing

What a message is comes from the sending number's registration and the message's wording, not from a label. Carriers approve a registration for one use case and treat anything outside it as a campaign violation, so we check it before they do (matches the registration's use case). A "category" on the request can make a message stricter ("marketing"), never looser:

The registration check. For a number linked to a registration (any use case but two-factor), and for a toll-free number verified through the console's form, the first message of each new kind is also compared with the registration or toll-free verification as you filed it (its use case, description and example messages) by an automated classifier. "Kind" means the text with names, numbers, amounts, emails and links masked, so "Your order 1234 shipped" and "Your order 5678 shipped" are one kind. What it can do:

• Refuse a kind that clearly doesn't match the registration, or a promotional one on a registration that isn't for marketing: 403 campaign_mismatch with mismatch: "off_use_case" (or "promotional"), checked_by: "consistency_check" and the fingerprint. The message says why.
• Count it as marketing when it is promotional on a mixed or low-volume registration, so every marketing check applies.
• Hold it for our team when it can't tell (403 held_for_review, nothing charged), at any age of the account.

It never makes a message looser than the table above. Its answer is kept per kind, so later messages of the same kind don't wait for it; editing the registration checks each kind again. If it can't run, a new kind is not sent (503 screen_unavailable). Think it got one wrong? Contact support: our team can approve that kind, and it then goes straight out.

Whether a message is marketing decides one thing for quiet hours: a single marketing send is refused by default, anything else is held.

Local time

We read the recipient's time zone from the area code of their number, for every US and Canadian area code. An area code tells us where a number was issued, not where the phone is: someone who moved and kept their number is read in their old time zone. It is the best signal available without location data, and it is an approximation.

• An area code that spans two time zones is treated as quiet when it is quiet in either one.
• A number whose area code shows no time zone (toll-free, for example) is held to every time zone in the contiguous US: it is texted between 11:00am and 9:00pm Eastern.
• Daylight time, and the places that do not observe it (Arizona, Hawaii, Saskatchewan), follow the standard time zone database.

Refuse or hold

curl https://api.jointextkit.com/v1/messages \
  -H "Authorization: Bearer $TEXTKIT_API_KEY" -H "Content-Type: application/json" \
  -d '{"to": "+12125550148", "body": "20% off this week. Reply STOP to opt out.",
       "category": "marketing", "quiet_hours": "defer"}'

Without quiet_hours, a message that is not marketing is held. For a marketing message the default depends on what is sending:

A broadcast sent at 10:00pm Eastern reaches recipients on the West Coast right away and recipients on the East Coast at 8:00am their time.

A held message that is somehow still in quiet hours when it comes due is held again, at most 3 times, and then blocked. An automatic carrier retry that would land in quiet hours fails with quiet_hours instead of going out, and is not charged.

Account default

Console → Compliance → Quiet hours sets the default for your account:

• Refuse single marketing sends, hold the rest (the default).
• Hold everything until 8:00am, single marketing sends included.

There is no off setting. A change is recorded in your audit log as quiet_hours.updated.

A quiet_hours value on a request always wins over the account default.

Test it

Quiet hours work the same with a test key. Two ways to trigger them:

• Send to +15005550015. For this number it is always night: a marketing message is refused, anything else is held. Only a message that reads as a one-time code goes out.
• Send to any real-looking number: it is read against its area code, as in live mode. Nothing is delivered.

What quiet hours do not do

• They apply only Florida's, Maryland's and Oklahoma's 8:00pm end. Other states' narrower hours, weekend hours and holiday restrictions are not applied. If you send into such a state, schedule accordingly.
• They do not know where a phone is, only where its number was issued.
• They do not decide whether a message may be sent at all. Consent, and the hours that apply where your recipients are, remain yours.

Links

From a number linked to a registration, or a toll-free number verified through our form, a message may link only to:

• the website domain on your registration or verification, and its subdomains;
• a domain in the example messages (or, for toll-free, the links in messages) you filed;
• a domain our team added for the registration at your request (a booking or payment page you use, for example).

Anything else is refused with 403 campaign_mismatch (mismatch: link_domain), and so is a link that redirects off those domains: we visit each link once for each kind of message and follow up to five redirects, without reading the page. We ask with HEAD (GET only if your site refuses HEAD), so a one-time link is not used up by the check. If the registration says its messages contain no links, any link is refused (mismatch: link). A domain made to look like another (paypa1.com, one letter off your own, an internationalized look-alike) is refused as phishing (403 forbidden, failure.code content_blocked). Your own test recipients are exempt. Public link shorteners are always refused.

What we add

Carriers expect two things in messages from a registered number, and we add them when they are missing instead of refusing the message (from a number linked to a registration; never to a one-time code, or to a reply within 4 hours of a message from the person):

• Your business name on a person's first message from that number. If the text does not name your business (any case or punctuation, with or without "LLC" or "Inc."), we put "Your Business: " in front, once per person and number.
• Opt-out wording on marketing: on the first marketing message to a person, and again if they have not had opt-out wording from that number in 30 days. If the text has none ("Reply STOP…", "Text STOP to end" and the like count), we add " Reply STOP to opt out." at the end.

The message's body is the text as sent, and disclosures_added (brand, opt_out) says what we added, on the API response, the message.sent event and in Logs. The added words can make a message one segment longer, and each segment is billed (rate plus carrier fee). Content checks run on the text as sent.

A registration also says whether its messages contain phone numbers. If it says they don't, a message with one written as a phone number (such as (415) 555-0132 or +1 415 555 0132; a bare run of ten digits, like an order number, does not count) is refused with 403 campaign_mismatch: remove the number, or contact support to update the registration.

Opt-in on file

A message goes only to a number with an opt-in on file when it is:

• marketing (which messages are marketing), from any number; or
• a recurring non-marketing message (a receipt, an alert, a reminder) from a number linked to a registration. Carriers expect consent for those too, and ask for proof of it when they audit a campaign.

Without one it is refused with 403 consent_required, stored in your log as a blocked message with that reason, and not charged. Never checked: one-time codes, a non-marketing reply within 4 hours of a message from the recipient, and non-marketing messages from a number with no registration.

An opt-in is on file when you recorded it, and the number has not opted out since, in any of these ways:

• POST /v1/consent/{phone} with "status": "opted_in" (add proof: where and how they agreed, the disclosure they saw; and campaign_id, the registration they opted in to);
• Record opt-in, a console button on the contact's page (or on Add contact, "They agreed to get texts"), or right from Send message when a message is refused for having none. It asks how they agreed, when, the page for a web form and the wording they saw, and records it for your registration with the same rules as the API (an opt-in given out loud is not offered for a marketing registration: those need written consent);
• a contact import row with an opt_in column (and a campaign_id column for the registration);
• the person texting START (or another opt-in keyword) to your number, which records an opt-in for that number's registration;
• a sign-up on the registration's hosted opt-in page;
• for a non-marketing message only, consent on the send itself ({ "source": "checkout", "collected_at": "..." }), which records the opt-in for the sending number's registration when none is on file.

Which opt-in counts depends on the sending number. From a number linked to a registration, the opt-in must be for that registration: consent is given to one business for one kind of message, and a reminders opt-in is not a promotions opt-in. From a number with no registration (the sandbox, toll-free and Canadian numbers, a number not yet linked), any opt-in on file with the account counts. The refusal names the registration it looked for (registration_id) and consent_scope. An opt-out is never narrower than the account. See consent is per registration and proof for marketing opt-ins.

Your verified numbers and your own phone are exempt, so you can always try a marketing message on yourself. A broadcast skips each recipient without an opt-in and sends to the rest; the skipped ones appear in its results and in your log.

We check that an opt-in is on file, not that the person really agreed or that the consent covers what you send: that stays yours to hold and produce on request (Messaging Policy).

Re-confirmation after 30 days

Some carriers require that a person who has not heard from a marketing program in 30 days confirms they still want it before the next promotional text. The check runs right after the opt-in check, for a marketing message from a number linked to a registration, when the recipient has not been messaged from that number in 30 days (the opt-in's own date counts as contact):

1. The message is held, and one re-confirmation text goes out first in your business's name, with STOP and HELP: "Acme: It has been a while. Reply YES to keep getting texts from Acme. Msg & data rates may apply. Reply STOP to cancel, HELP for help."
2. The request answers 403 reconfirmation_pending with expires_at and held: true; the held message is in your log as blocked with that reason, and message.blocked carries it. Nothing is charged.
3. If they reply YES (or Y, OK, SURE, CONFIRM, START, JOIN) within 7 days, the held message is queued and sent by itself through the whole pipeline, and message.opted_in fires with reconfirmed: true and released_message_ids. Marketing to them resumes.
4. Other marketing messages to the same number while the question is open answer 403 reconfirmation_pending (with held: false): the person is asked once, not once per message.
5. No reply in 7 days: the held message is dropped, its row in Logs changes to reconfirmation_expired (announced again on message.blocked with the same message_id), and marketing to that number is refused with 403 reconfirmation_expired until they opt in again: a YES or START reply, or a new opt-in you record with proof.

Transactional messages, one-time codes, marketing from a number with no registration, and your verified test numbers are never held. A STOP ends the question like any other opt-out.

Turning it off

An admin can turn re-confirmation off on the console Compliance page, after acknowledging that the account handles it itself; the acknowledgment and the change are recorded in the audit log as reconfirmation.updated. It is never off by default.

Test it

In the sandbox, link a test number to a registration with use case marketing, record an opt-in for that registration with "collected_at" more than 30 days ago, and send a marketing message to the number: the request answers reconfirmation_pending and the sandbox records the re-confirmation text. Simulate a YES with POST /v1/test/inbound and the held message goes out on the next queue run.

Review of new kinds of message

During your account's first 30 days of live sending, our team looks at each new kind of message from a number linked to a registration, or a toll-free number verified through the console's form, before it goes out. It runs after the content screen, so we only ever look at text the screen passed.

A kind of message is the text with the parts that change masked: names, numbers, amounts, dates, codes and email addresses, and links reduced to their domain. "Hi Sam, order 1234 shipped" and "Hi Alex, order 5678 shipped" are one kind; a broadcast or batch is one kind for all its recipients, whatever its {{merge}} fields hold.

1. The first messages of a new kind are held: the request answers 403 held_for_review with held: true, fingerprint (the kind's id), registration_id and expires_at. Each is in your log as blocked with that reason and announced on message.blocked. Nothing is charged.
2. We aim to review within one business day. Approved: every held message of that kind is sent by itself through all the checks again (quiet hours and the opt-out list included), its row in Logs says it was sent as a new message, and later messages of that kind go straight out. template.approved is in your audit log.
3. Rejected: the held messages are dropped, their rows change to review_rejected (announced again on message.blocked with the same message_id), and later messages of that kind from that registration are refused with 403 review_rejected. The reason is in the message, and your audit log records it as template.rejected. This applies after your first 30 days too.
4. Not reviewed within 3 days: the held messages are dropped and their rows change to review_expired. Send again: if the kind has been approved since, it goes straight out.

Up to 10,000 messages of one kind are held; past that a send answers held_for_review with held: false and is not kept, so send it again once the kind is approved. A broadcast's results count its held messages as not sent; once approved they go out as individual messages.

Exempt: your verified numbers and your own phone (so you can try anything on yourself first), one-time codes from a two-factor registration, and the confirmation text of a hosted opt-in page. Keyword replies, auto-replies and Verify codes are not held. A quick way through: send each kind of message to yourself, then once to a real recipient, early.

Our team can keep reviewing an account after 30 days, or stop sooner; the change is in your audit log as template_review.updated.

Sending pace

Carriers limit how fast one registration may send. Every live message from a number linked to a registration counts against the registration's pace, whichever of its numbers sends it:

• Batches, broadcasts and scheduled messages over the pace wait for the next minute and go out then. Nothing fails and nothing is charged twice; the batch simply takes longer.
• A direct send (POST /v1/messages, the console) over the pace is refused with 429 rate_limited and a Retry-After, recorded as blocked, not charged. Send it again, or use a batch.
• Carriers also cap how many messages a business may send some of their subscribers in a day. A message refused for that comes back failed with rate_limited: send it again the next day.

These are the carriers' defaults for a new registration; a registration with a higher limit is not paced faster yet.

Daily caps

Two daily limits count people and messages per day (UTC). Over either, a batch, broadcast or scheduled message waits for the next day and goes out then; a direct send is refused with 429 rate_limited and a Retry-After until midnight UTC, recorded as blocked, not charged. Your verified test recipients are never counted or refused.

Per-person limits

• Bursts. No more than 10 messages from your account to one person in 5 minutes, or 25 while they are texting you back (they wrote within the last hour). Over it: 429 rate_limited with a Retry-After.
• One person, few numbers. A person your account texted from two of its numbers in the last 24 hours is not texted from a third: 403 sender_rotation, naming the two numbers to use. Carriers treat one person reached from many numbers as dodging their filters. A reply to someone who texted the number is never refused, and a sender pool (sticky by default) keeps each person on one number.
• State limit on marketing. Florida, Maryland and Oklahoma allow 3 marketing texts to one person in 24 hours, read from the area code. A 4th from your account, whatever it is about, gets 429 rate_limited with a Retry-After; a batch, broadcast or scheduled message waits until it is allowed. Replies within 4 hours of the person's own text don't count.

The enforcement ladder

Every registration is judged on its last 7 days: complaints (replies like "spam", "who is this", "never signed up", "reported" or "wrong number", and verified reports from people we texted, see below), the share of its messages carriers filtered, its opt-out rate, strikes, and kinds of message our team rejected. Rates count once it has sent 200 messages in the 7 days.

Each step is recorded in your audit log with its reasons. A step's webhook event (compliance.flagged for a warning or half speed, compliance.paused when paused, compliance.resumed when our team lifts it) carries scope ("registration" with registration_id, or "account"), the level, and the reasons. The automatic pause of all sending sends compliance.paused with scope: "account". The console shows a banner with the reasons and an Appeal form (owners and admins). A registration moves back down only when our team moves it, with a reason.

Strikes and the automatic pause. A message blocked as phishing, impersonation or fraud, a kind of message our team rejected, texting people from a third number on three or more people in a day, or abuse our team confirms is a strike. Three phishing, impersonation or fraud strikes to two or more people within 7 days pause all of your account's live sending (403 account_paused) until our team reviews it. Your keys and data keep working and batches wait.

Complaints and reports. We read replies for complaint phrases and keep only that a complaint happened, never the reply. A "wrong number" reply also opts that person out. Anyone can report a text at /report; when it matches a text your number sent them in the last 30 days, it counts as a complaint and they are opted out. Their number is never shown to you.

Opt-out rate

Carriers watch how many people opt out of a brand's messages. We count, for each registration over the last 24 hours, the messages carriers accepted from its numbers and the people who opted out by texting them (STOP, or a plain "stop texting me").

A paused registration stays paused until our team has looked at it with you and resumes it (compliance.resumed); the 24-hour count then starts again. Opt-outs you record yourself (the consent API, an import) are not counted. Your verified numbers are exempt, so you can still test.

A high opt-out rate almost always means some people did not expect the messages: check the opt-in, that every message names your business, and how often you send.

Test it

With a test key, +15005550016 never has an opt-in: send it a marketing message to see the refusal. The other 500-555 numbers count as opted in. A real-looking number is checked exactly as in live mode, so record its opt-in first.

What is not checked

These are not part of the pipeline. Nothing on this page should be read as covering them.

• Reassigned numbers. We do not check whether a number has changed hands since the person gave you consent. No reassigned-number database is queried.
• Litigator and complainer lists. We do not screen recipients against any list of known litigants or serial complainants.
• Do-not-call registries. We do not check national or state do-not-call lists.
• Consent itself. For marketing messages we check that an opt-in is on file, and we enforce opt-outs, but we cannot verify that a recipient really agreed to hear from you, or that the consent covers what you send. That stays your responsibility.
• Other state sending rules. Quiet hours use the federal 8:00am to 9:00pm window, and 8:00pm for Florida, Maryland and Oklahoma numbers. Other states' stricter hours, weekend hours and holiday rules are not applied.
• The recipient's actual location. Local time is read from the number's area code, which says where the number was issued, not where the phone is.

You remain responsible for having consent for every recipient, for classifying your traffic correctly, and for following the laws that apply to your messages. These checks enforce specific rules by default; they are not legal advice and do not make a messaging program compliant on their own. See the Messaging Policy.