When a customer says "I never agreed to these texts," the first question is always the same: show me the record. If the answer lives in three systems and a Slack thread, you lose time and, sometimes, the argument. A good audit log makes that question a five-minute lookup.
This guide is for compliance, security and engineering people at a platform that sends texts for its customers. We'll go through what to log for each send, how to log opt-outs and consent, what to keep and for how long, and where your SMS vendor's records stop and yours have to begin. That last part is the one most teams get wrong.
Know where your vendor's record ends
Start with an honest split. A sending API can record some things for you and can't record others.
On Ready, an API send that sets consent_attested records the sender's attestation: who sent, to how many, and when. That's an audit trail of the sender's promise. It isn't a per-contact consent record. Ready doesn't store a recipient's opt-in time, wording or page URL, and a keyword reply creates none. The one exception is a sign-up on a Ready-hosted opt-in page, which is stored per contact with the time, IP and exact wording; for a copy of those, email support@tryready.com. Ready's own message history also holds what was sent and received.
Until January 20, 2027 (UTC), an API send without consent_attested still goes out, with a warning and no attestation. From that date it's refused with 403 api_consent_attested_required. So if you want an unbroken trail, set the flag on every send now.
That means the proof of a person's consent is yours to keep. Compliance is the sender's responsibility, and your log is how you show it.
The record for each send
Log one row per send attempt, written before the call and updated after. These fields answer most disputes:
| Field | Why it matters |
|---|---|
| Your internal message ID | Joins every other record |
| Tenant (customer) and sub-account | Shows whose traffic it was |
| Acting user or system | Who or what triggered the send |
| Recipient, stored per your redaction rules | Who it went to |
| Template ID and version, or the body hash | What was said, without storing it twice |
| Consent record ID | Points to the proof of agreement |
consent_attested value sent | Ties your row to the vendor's attestation |
| Idempotency key | Proves a retry wasn't a second send |
| Request time, response code, vendor message ID | Links to the vendor's record |
| Outcome: sent, held, refused, failed | Shows what the system decided |
| Status callbacks with timestamps | Delivery trail |
Keep the vendor message ID from the response so you can reconcile your log against what was sent and billed. The message status state machine post describes the states your outcome column should map to. If you store bodies, see redacting phone numbers and message bodies from logs first, because an audit log is also a data store that has to be protected.
The consent record you keep
Per contact, store at least the following. This is your proof, so write it at the moment of agreement, not later.
- The time of agreement, in UTC.
- The exact wording the person saw, or a version ID that points to it.
- The source: form, checkbox, signed document, a text they sent first.
- The page or document location, and the IP or device where you have it.
- Who collected it: your customer, your platform, an import.
- Any later change: withdrawn, replaced, re-confirmed.
Imports deserve their own line. If a customer uploads a list, log who uploaded it, when, and what they attested about it. A list with no source is the weakest record you can have. Our consent record schema post gives a table layout for this.
Log the decisions, not just the sends
Auditors and plaintiffs ask about texts that weren't sent as often as texts that were. Record the refusals too, with the reason.
- Opt-out refused. An opted-out number is refused up front and isn't charged. Log it with the opt-out source and time. Before a send from another tool or after a provider switch, check
GET /v1/opt-outs/:phoneand log the answer. A STOP always blocks that number in the sub-account that received it; whether it also reaches the others depends on an account setting, so log the check, not an assumption. - Quiet hours. An API text is held only if the window opens within 6 hours; otherwise it isn't sent and the API answers
409 QUIET_HOURS_BLOCK. Log the block and, when your system sends again, the new time. A reply to someone who texted in the last 24 hours can go out at any hour, so log that exception when you rely on it. - Scrubbing. If you switch on screening against litigator and Do Not Call lists, log the result and the list check time. The TCPA and DNC scrub API post covers what it checks.
Opt-outs deserve a durable trail of their own: when the STOP arrived, which number it came to, and when your system honored it. Handling opt-outs explains the flow.
Retention: decide, write it down, then delete on purpose
There's no single retention period that fits everyone. Consent and send records are usually kept long enough to cover the period when someone could bring a claim, and that varies by law and state. Ask your counsel for the number, write it into a retention policy, and apply it to consent records, send logs and bodies separately. Bodies carry the most personal data and often deserve a shorter life than the metadata that proves the send.
Keep in mind that deleting a person's data and keeping proof of consent can pull in opposite directions. Decide in advance which records survive a deletion request and why. The data retention and deletion policy post lays out the decision.
On the vendor side, Ready's call recordings and transcripts are kept while the account is active, with no age-based delete, and deleting a contact deletes its calls' recordings and transcripts. If your audit log links to a recording, plan for it disappearing when the contact does.
Make the log hard to change
A log that anyone can edit isn't evidence.
- Write rows once; corrections are new rows that point at the old one.
- Restrict write access to the service that sends, and read access to named roles.
- Log who reads sensitive records, not just who writes.
- Ship a copy to storage that the application can't modify.
- Test a lookup quarterly: pick a random recipient and see whether you can produce consent, sends, opt-outs and delivery within an hour.
A short worked example
A customer complains about a text sent on a Tuesday at 7 pm. Your lookup should return: the send row (tenant, user, template version), the consent record (a web form checkbox, with wording version and timestamp), the idempotency key showing one send, the vendor message ID, the delivery callback, and the opt-out check made that morning. If the person had replied STOP the week before, the log shows a refusal and no text, and the complaint is answered in one line. That outcome is what the logging is for.
Frequently asked questions
Does Ready store a contact's consent?
Not per contact, except for sign-ups on a Ready-hosted opt-in page. It records the sender's attestation on a send, and the per-contact proof is yours to keep.
Should we log message bodies?
Log a template ID and version or a hash by default. Store full bodies only if you need them, and protect them like any personal data.
Can the audit log replace our consent records?
No. They answer different questions: the send log shows what happened, and the consent record shows why you were allowed to send.
Next step
Pick one recent send and try to reconstruct it end to end: consent, content, opt-out check, outcome and delivery. Wherever you got stuck is the field to add. The compliance checklist before launching texting is a good companion for the gaps.