Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Retrieve and Modify Message History


This guide will show you how you can search, retrieve, and modify the messages you send or receive with Programmable Messaging, using the Message Resource.

A Message resource represents an inbound or outbound message. Twilio creates a Message when any of the following occur:

  • You create a Message resource (i.e., send an outbound message) via the REST API
  • Twilio executes a <Message> TwiML instruction
  • Someone sends a message to one of your Twilio numbers or messaging channel addresses
(information)

Info

For step-by-step instructions for sending your first SMS message with Twilio, check out one of the SMS quickstarts.

For detailed instructions on setting up your local environment to code in all of our supported programming languages, see the Environment Setup section of this Guide.

Looking to send WhatsApp messages with Twilio? Try one of the WhatsApp quickstarts.

If you're looking for how to respond to incoming messages, check out the How to Receive and Reply to SMS Messages tutorial.


Search Previous Messages

search-previous-messages page anchor

When you send an SMS or MMS message via the REST API, using the <Message> verb in TwiML, or someone sends a message to one of your Twilio numbers or other channels, Twilio creates a Message instance resource. The Messages list resource represents the set of messages sent from and received by an account.

Retrieving sent and received messages from history can be achieved by querying the Messages list resource. Here you can see how to retrieve all messages from your account:

List all Messages in your account

list-all-messages-in-your-account page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.messages.list({limit: 20})
_10
.then(messages => messages.forEach(m => console.log(m.sid)));

Output

_70
{
_70
"end": 1,
_70
"first_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages.json?To=%2B123456789&From=%2B987654321&DateSent%3E=2008-01-02&PageSize=2&Page=0",
_70
"next_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages.json?To=%2B123456789&From=%2B987654321&DateSent%3E=2008-01-02&PageSize=2&Page=1&PageToken=PAMMc26223853f8c46b4ab7dfaa6abba0a26",
_70
"page": 0,
_70
"page_size": 2,
_70
"previous_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages.json?To=%2B123456789&From=%2B987654321&DateSent%3E=2008-01-02&PageSize=2&Page=0",
_70
"messages": [
_70
{
_70
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_70
"api_version": "2010-04-01",
_70
"body": "testing",
_70
"date_created": "Fri, 24 May 2019 17:44:46 +0000",
_70
"date_sent": "Fri, 24 May 2019 17:44:50 +0000",
_70
"date_updated": "Fri, 24 May 2019 17:44:50 +0000",
_70
"direction": "outbound-api",
_70
"error_code": null,
_70
"error_message": null,
_70
"from": "+12019235161",
_70
"messaging_service_sid": null,
_70
"num_media": "0",
_70
"num_segments": "1",
_70
"price": "-0.00750",
_70
"price_unit": "USD",
_70
"sid": "SMded05904ccb347238880ca9264e8fe1c",
_70
"status": "sent",
_70
"subresource_uris": {
_70
"media": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMded05904ccb347238880ca9264e8fe1c/Media.json",
_70
"feedback": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMded05904ccb347238880ca9264e8fe1c/Feedback.json"
_70
},
_70
"tags": {
_70
"campaign_name": "Spring Sale 2022",
_70
"message_type": "cart_abandoned"
_70
},
_70
"to": "+18182008801",
_70
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMded05904ccb347238880ca9264e8fe1c.json"
_70
},
_70
{
_70
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_70
"api_version": "2010-04-01",
_70
"body": "look mom I have media!",
_70
"date_created": "Fri, 24 May 2019 17:44:46 +0000",
_70
"date_sent": "Fri, 24 May 2019 17:44:49 +0000",
_70
"date_updated": "Fri, 24 May 2019 17:44:49 +0000",
_70
"direction": "inbound",
_70
"error_code": 30004,
_70
"error_message": "Message blocked",
_70
"from": "+12019235161",
_70
"messaging_service_sid": null,
_70
"num_media": "3",
_70
"num_segments": "1",
_70
"price": "-0.00750",
_70
"price_unit": "USD",
_70
"sid": "MMc26223853f8c46b4ab7dfaa6abba0a26",
_70
"status": "received",
_70
"subresource_uris": {
_70
"media": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/MMc26223853f8c46b4ab7dfaa6abba0a26/Media.json",
_70
"feedback": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/MMc26223853f8c46b4ab7dfaa6abba0a26/Feedback.json"
_70
},
_70
"tags": {
_70
"campaign_name": "Spring Sale 2022",
_70
"message_type": "cart_abandoned"
_70
},
_70
"to": "+18182008801",
_70
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/MMc26223853f8c46b4ab7dfaa6abba0a26.json"
_70
}
_70
],
_70
"start": 0,
_70
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages.json?To=%2B123456789&From=%2B987654321&DateSent%3E=2008-01-02&PageSize=2&Page=0"
_70
}

If you'd like to have Twilio narrow down this list of messages for you, you can do so by specifying a To number, From number, and a DateSent. The following example shows passing all three but you can pass any combination of parameters you need. This example filters messages for those sent from a specific number to another specific number on or after a certain date:

List Messages matching filter criteria

list-messages-matching-filter-criteria page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_15
// Download the helper library from https://www.twilio.com/docs/node/install
_15
// Find your Account SID and Auth Token at twilio.com/console
_15
// and set the environment variables. See http://twil.io/secure
_15
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_15
const authToken = process.env.TWILIO_AUTH_TOKEN;
_15
const client = require('twilio')(accountSid, authToken);
_15
_15
client.messages
_15
.list({
_15
dateSent: new Date(Date.UTC(2016, 7, 31, 0, 0, 0)),
_15
from: '+15017122661',
_15
to: '+15558675310',
_15
limit: 20
_15
})
_15
.then(messages => messages.forEach(m => console.log(m.sid)));

Output

_70
{
_70
"end": 1,
_70
"first_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages.json?To=%2B123456789&From=%2B987654321&DateSent%3E=2008-01-02&PageSize=2&Page=0",
_70
"next_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages.json?To=%2B123456789&From=%2B987654321&DateSent%3E=2008-01-02&PageSize=2&Page=1&PageToken=PAMMc26223853f8c46b4ab7dfaa6abba0a26",
_70
"page": 0,
_70
"page_size": 2,
_70
"previous_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages.json?To=%2B123456789&From=%2B987654321&DateSent%3E=2008-01-02&PageSize=2&Page=0",
_70
"messages": [
_70
{
_70
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_70
"api_version": "2010-04-01",
_70
"body": "testing",
_70
"date_created": "Fri, 24 May 2019 17:44:46 +0000",
_70
"date_sent": "Fri, 24 May 2019 17:44:50 +0000",
_70
"date_updated": "Fri, 24 May 2019 17:44:50 +0000",
_70
"direction": "outbound-api",
_70
"error_code": null,
_70
"error_message": null,
_70
"from": "+12019235161",
_70
"messaging_service_sid": null,
_70
"num_media": "0",
_70
"num_segments": "1",
_70
"price": "-0.00750",
_70
"price_unit": "USD",
_70
"sid": "SMded05904ccb347238880ca9264e8fe1c",
_70
"status": "sent",
_70
"subresource_uris": {
_70
"media": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMded05904ccb347238880ca9264e8fe1c/Media.json",
_70
"feedback": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMded05904ccb347238880ca9264e8fe1c/Feedback.json"
_70
},
_70
"tags": {
_70
"campaign_name": "Spring Sale 2022",
_70
"message_type": "cart_abandoned"
_70
},
_70
"to": "+18182008801",
_70
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMded05904ccb347238880ca9264e8fe1c.json"
_70
},
_70
{
_70
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_70
"api_version": "2010-04-01",
_70
"body": "look mom I have media!",
_70
"date_created": "Fri, 24 May 2019 17:44:46 +0000",
_70
"date_sent": "Fri, 24 May 2019 17:44:49 +0000",
_70
"date_updated": "Fri, 24 May 2019 17:44:49 +0000",
_70
"direction": "inbound",
_70
"error_code": 30004,
_70
"error_message": "Message blocked",
_70
"from": "+12019235161",
_70
"messaging_service_sid": null,
_70
"num_media": "3",
_70
"num_segments": "1",
_70
"price": "-0.00750",
_70
"price_unit": "USD",
_70
"sid": "MMc26223853f8c46b4ab7dfaa6abba0a26",
_70
"status": "received",
_70
"subresource_uris": {
_70
"media": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/MMc26223853f8c46b4ab7dfaa6abba0a26/Media.json",
_70
"feedback": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/MMc26223853f8c46b4ab7dfaa6abba0a26/Feedback.json"
_70
},
_70
"tags": {
_70
"campaign_name": "Spring Sale 2022",
_70
"message_type": "cart_abandoned"
_70
},
_70
"to": "+18182008801",
_70
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/MMc26223853f8c46b4ab7dfaa6abba0a26.json"
_70
}
_70
],
_70
"start": 0,
_70
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages.json?To=%2B123456789&From=%2B987654321&DateSent%3E=2008-01-02&PageSize=2&Page=0"
_70
}


Retrieve a Single Message

retrieve-a-single-message page anchor

If you know the message SID (i.e. the message's unique identifier), then you can retrieve that specific message directly.

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.messages('MM800f449d0399ed014aae2bcc0cc2f2ec')
_10
.fetch()
_10
.then(message => console.log(message.to));

Output

_25
{
_25
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_25
"api_version": "2010-04-01",
_25
"body": "testing",
_25
"date_created": "Fri, 24 May 2019 17:18:27 +0000",
_25
"date_sent": "Fri, 24 May 2019 17:18:28 +0000",
_25
"date_updated": "Fri, 24 May 2019 17:18:28 +0000",
_25
"direction": "outbound-api",
_25
"error_code": 30007,
_25
"error_message": "Carrier violation",
_25
"from": "+12019235161",
_25
"messaging_service_sid": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_25
"num_media": "0",
_25
"num_segments": "1",
_25
"price": "-0.00750",
_25
"price_unit": "USD",
_25
"sid": "MM800f449d0399ed014aae2bcc0cc2f2ec",
_25
"status": "sent",
_25
"subresource_uris": {
_25
"media": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMb7c0a2ce80504485a6f653a7110836f5/Media.json",
_25
"feedback": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMb7c0a2ce80504485a6f653a7110836f5/Feedback.json"
_25
},
_25
"to": "+18182008801",
_25
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMb7c0a2ce80504485a6f653a7110836f5.json"
_25
}

How might you know the SID? When sending a message using the REST API, you will receive a Message instance resource as the response from Twilio. Using this, you can inspect the Sid property of the resource. Read more about sending messages in our guide on the topic.

When using the <Message> verb in TwiML, you will need to specify a webhook URL the action attribute to have Twilio call your webhook when the status of the message changes. Your webhook will be passed a MessageSid parameter identifying the incoming message. Read our guide on tracking message status for more on how to do this.

When receiving a message, your webhook will be passed a MessageSid parameter identifying the incoming message. You can learn more about receiving messages here.

However you obtain the SID, you can immediately request the message using the above code, or, you can save the SID in a database for later recall.


Delete or Redact Previously Sent Messages

delete-or-redact-previously-sent-messages page anchor

If you want to delete a message from history, you can easily do so by deleting the Message instance resource.

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.messages('MM800f449d0399ed014aae2bcc0cc2f2ec').remove();

Perhaps you want to redact the body of the message for security purposes, but you don't want to delete the message from history entirely. Redacting a message is done by posting an empty body to the message resource (i.e., this is a specific use of the Message update call):

Redact the body of a Message

redact-the-body-of-a-message page anchor
Node.js
Python
C#
Java
PHP
Ruby
curl

_11
// Download the Node helper library from twilio.com/docs/node/install
_11
// These consts are your accountSid and authToken from https://www.twilio.com/console
_11
// To set up environmental variables, see http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client
_11
.messages('MM800f449d0399ed014aae2bcc0cc2f2ec')
_11
.update({ body: '' })
_11
.then(message => process.stdout.write(message.body));

Output

_19
{
_19
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_19
"api_version": "2010-04-01",
_19
"body": "",
_19
"error_code": null,
_19
"error_message": null,
_19
"num_segments": "1",
_19
"num_media": "0",
_19
"date_created": "Mon, 16 Aug 2010 03:45:01 +0000",
_19
"date_sent": "Mon, 16 Aug 2010 03:45:03 +0000",
_19
"date_updated": "Mon, 16 Aug 2010 03:45:03 +0000",
_19
"direction": "outbound-api",
_19
"from": "+14158141829",
_19
"price": "-0.02000",
_19
"sid": "MM800f449d0399ed014aae2bcc0cc2f2ec",
_19
"status": "sent",
_19
"to": "+15558675310",
_19
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/MM800f449d0399ed014aae2bcc0cc2f2ec.json"
_19
}


Rate this page: