# SMS (Twilio)

## Overview

MailTrixy integrates with Twilio to enable two-way SMS messaging. Your customers can text your business number, and MailTrixy will display the conversation in the unified inbox alongside emails and other channels. AI replies work on SMS conversations as well, generating concise responses appropriate for the SMS format.

## Twilio Account Setup

1. Go to twilio.com/try-twilio and create a free trial account.
2. Verify your email and phone number.
3. Complete the onboarding questionnaire (select "SMS" as your product of interest).
4. Your trial account comes with a small credit balance for testing.

> Note: Trial accounts can only send SMS to verified phone numbers. To send to any number, you must upgrade to a paid Twilio account and register your use case (A2P 10DLC (Application-to-Person 10-Digit Long Code) registration for US numbers, or a Messaging Service for other countries).

## API Credentials

MailTrixy needs two pieces of information from your Twilio account:

1. Log in to the Twilio Console.
2. On the dashboard, find your Account SID and Auth Token.
3. Copy both values.
4. In MailTrixy, go to Settings → Channels → SMS (Twilio).
5. Paste the Account SID and Auth Token.
6. Click Test Connection to verify.

> Security: Your Auth Token is a secret. Never share it publicly or commit it to version control. MailTrixy stores it encrypted in your database.

## Phone Number Purchase

You need a Twilio phone number to send and receive SMS.

1. In the Twilio Console, go to Phone Numbers → Buy a Number.
2. Select your country and check the SMS capability filter.
3. Choose a number (local, toll-free, or short code) and click Buy.
4. Copy the phone number (in E.164 format (international phone number format: a plus sign followed by country code and number), e.g., `+15551234567`).
5. Paste it in MailTrixy at Settings → Channels → SMS (Twilio) → Phone Number.

Twilio will automatically configure the webhook URL for incoming messages. If you need to set it manually, use:

    https://yourdomain.com/api/webhooks/twilio-sms

Set the HTTP method to POST.

## Incoming and Outgoing SMS

### Incoming SMS

When someone texts your Twilio number:

1. Twilio sends a webhook to MailTrixy with the message content, sender number, and timestamp.
2. MailTrixy creates a new conversation (or adds to an existing one if the sender has messaged before).
3. The message appears in your unified inbox with an SMS badge.
4. If AI is enabled for the SMS channel, the AI generates a reply draft (or auto-sends if configured).

### Outgoing SMS

To send an SMS from MailTrixy:

1. Open a conversation or start a new one.
2. Select SMS as the channel.
3. Type your message (keep it under 160 characters for a single SMS segment, or MailTrixy will automatically handle multi-part messages).
4. Click Send.

Delivery status (queued, sent, delivered, failed) is updated in real-time as Twilio reports status callbacks.

## Opt-Out Handling

Compliance with SMS regulations requires honoring opt-out requests. MailTrixy handles this automatically:

- Automatic detection: If a customer replies with "STOP", "UNSUBSCRIBE", "CANCEL", "END", or "QUIT", MailTrixy marks them as opted out.
- Blocked sending: MailTrixy will not send any further SMS messages to opted-out contacts. Attempts to message them will show a warning.
- Opt-back-in: If the contact texts "START" or "UNSTOP", they are automatically opted back in.
- Twilio Advanced Opt-Out: Twilio also handles opt-out at the carrier level. Both systems work together to ensure compliance.

> Compliance: In the United States, you must register for A2P 10DLC (Application-to-Person 10-Digit Long Code) — a U.S. regulatory requirement that verifies your business identity for sending SMS. Without registration, carriers may block or filter your messages. Visit Twilio Console → Messaging → Compliance to complete registration.