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:

FieldWhy it matters
Your internal message IDJoins every other record
Tenant (customer) and sub-accountShows whose traffic it was
Acting user or systemWho or what triggered the send
Recipient, stored per your redaction rulesWho it went to
Template ID and version, or the body hashWhat was said, without storing it twice
Consent record IDPoints to the proof of agreement
consent_attested value sentTies your row to the vendor's attestation
Idempotency keyProves a retry wasn't a second send
Request time, response code, vendor message IDLinks to the vendor's record
Outcome: sent, held, refused, failedShows what the system decided
Status callbacks with timestampsDelivery 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.

  1. The time of agreement, in UTC.
  2. The exact wording the person saw, or a version ID that points to it.
  3. The source: form, checkbox, signed document, a text they sent first.
  4. The page or document location, and the IP or device where you have it.
  5. Who collected it: your customer, your platform, an import.
  6. 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/:phone and 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.