Skill: sendly-live/sms-best-practices (version 1.0.0)

--- name: sms-best-practices description: Provides SMS compliance, formatting, and delivery best practices for the Sendly API. Covers TCPA compliance, quiet hours, opt-out handling, E.164 phone formatting, message segmentation, and carrier verification. Applies when building SMS features that must be compliant and deliverable. --- # SMS Best Practices ## Phone number formatting Always use E.164 format: `+{country_code}{number}` with no spaces, dashes, or parentheses. | Input | E.164 | Valid? | |---|---|---| | (415) 555-1234 | +14155551234 | After formatting | | 415-555-1234 | +14155551234 | After formatting | | +14155551234 | +14155551234 | Yes | | 4155551234 | +14155551234 | Need country code | ## Message types and compliance **transactional**: OTP codes, order confirmations, appointment reminders, account alerts, shipping updates. Allowed 24/7. The recipient has an existing relationship with the sender. **marketing**: Promotions, sales, newsletters, product announcements. Subject to: - Quiet hours: 9pm–8am in the recipient's local timezone - Prior express written consent required (TCPA) - Must include opt-out instructions Misclassifying marketing as transactional violates TCPA and can result in fines up to $1,500 per message. ## Opt-out handling Sendly automatically handles opt-outs. When a recipient replies STOP, UNSUBSCRIBE, CANCEL, END, or QUIT: - The number is added to the opt-out list - Future sends to that number return `opted_out` error - An `opt_out.created` webhook event fires Do not attempt to send to opted-out numbers. Check `message.status` for `opted_out` errors. Opt-out status is checked automatically when sending — the API returns an `opted_out` error if the recipient has unsubscribed. ## Quiet hours Marketing messages are blocked during quiet hours (9pm–8am recipient local time). Sendly enforces this automatically — the API returns `quiet_hours_violation` if you attempt a marketing send during quiet hours. Transactional messages are exempt from quiet hours. ## Message segmentation SMS messages are limited to 160 characters (GSM-7 encoding) or 70 characters (UCS-2 for emoji/Unicode). Longer messages are split into segments: | Encoding | Single segment | Multi-segment per part | |---|---|---| | GSM-7 (ASCII) | 160 chars | 153 chars | | UCS-2 (emoji/Unicode) | 70 chars | 67 chars | Each segment costs credits separately. Keep messages concise. ## SHAFT content filtering Sendly blocks messages containing prohibited content categories (SHAFT): - **S**ex/adult content - **H**ate speech - **A**lcohol - **F**irearms - **T**obacco/drugs Messages flagged by SHAFT filtering return `content_violation` error. ## Credit costs - US/CA: 2 credits ($0.02) per message segment - International: varies by destination (see country requirements) - 1 credit = $0.01 Check balance: `GET /api/v1/credits` ## Carrier verification To send SMS in the US/CA, your toll-free number must be verified by carriers. This requires: - Business name and address - Website URL (use hosted business pages if you don't have one) - Use case description - Sample messages Verification takes 1–5 business days. Use sandbox mode (`sk_test_*` keys) while waiting. ## Common errors | Error | Cause | Fix | |---|---|---| | `invalid_phone_number` | Not E.164 format | Format as +{country}{number} | | `insufficient_credits` | Balance too low | Purchase credits at sendly.live | | `quiet_hours_violation` | Marketing during 9pm–8am | Use transactional type or wait | | `opted_out` | Recipient unsubscribed | Do not retry — respect opt-out | | `content_violation` | SHAFT filter triggered | Revise message content | | `not_verified` | Number not carrier-verified | Complete verification at sendly.live | ## Full reference - Compliance docs: https://sendly.live/docs/concepts/compliance - Quiet hours: https://sendly.live/docs/quiet-hours - Country requirements: https://sendly.live/docs/country-requirements - Opt-out handling: https://sendly.live/docs/how-to/handle-opt-outs


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal:  | SkillSpector: clean (LOW)