# Media subresource Media is a subresource of [Messages](/docs/messaging/api/message-resource) and represents a piece of media, such as an image, that is associated with a Message. Twilio creates a Media subresource and stores the contents of the media when the following events occur: 1. You [send an MMS](/docs/messaging/tutorials/how-to-send-sms-messages) with an image via Twilio. 2. You [send a WhatsApp message with an image](/docs/whatsapp/tutorial/send-and-receive-media-messages-twilio-api-whatsapp) via Twilio. 3. You receive media in a message sent to one of your Twilio numbers or messaging channel addresses. Twilio retains the stored media until you [delete the related Media subresource instance.](#delete-media) > \[!WARNING] > > Twilio enforces [HTTP Basic Authentication](/docs/glossary/what-is-basic-authentication) for all media URLs. Authenticate using an [API key](/docs/iam/api-keys) as the username and an API key secret as the password. You can also use your Account SID and Auth Token when testing locally. > \[!WARNING] > > You can send messages using Twilio with up to 10 media files that have a total size of up to 5MB. Twilio resizes images as necessary for successful delivery based on carrier specifications. Twilio rejects messages with over 5MB of media. ## Medium Properties ```json {"type":"object","refName":"api.v2010.account.message.media","modelName":"api_v2010_account_message_media","properties":{"account_sid":{"type":"string","minLength":34,"maxLength":34,"pattern":"^AC[0-9a-fA-F]{32}$","nullable":true,"description":"The SID of the [Account](/docs/iam/api/account) associated with this Media resource."},"content_type":{"type":"string","nullable":true,"description":"The default [MIME type](https://en.wikipedia.org/wiki/Internet_media_type) of the media, for example `image/jpeg`, `image/png`, or `image/gif`."},"date_created":{"type":"string","format":"date-time-rfc-2822","nullable":true,"description":"The date and time in GMT when this Media resource was created, specified in [RFC 2822](https://www.ietf.org/rfc/rfc2822.txt) format."},"date_updated":{"type":"string","format":"date-time-rfc-2822","nullable":true,"description":"The date and time in GMT when this Media resource was last updated, specified in [RFC 2822](https://www.ietf.org/rfc/rfc2822.txt) format."},"parent_sid":{"type":"string","minLength":34,"maxLength":34,"pattern":"^(SM|MM)[0-9a-fA-F]{32}$","nullable":true,"description":"The SID of the Message resource that is associated with this Media resource."},"sid":{"type":"string","minLength":34,"maxLength":34,"pattern":"^ME[0-9a-fA-F]{32}$","nullable":true,"description":"The unique string that identifies this Media resource."},"uri":{"type":"string","nullable":true,"description":"The URI of this Media resource, relative to `https://api.twilio.com`."}}} ``` ## Retrieve Media `GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages/{MessageSid}/Media/{Sid}.json` Returns a single Media subresource using one of several representations: * `content-type` * `XML` * `JSON` ## Default: content-type Without an extension, Twilio returns the media using the mime-type it assigned when it generated the media. ```bash GET /2010-04-01/Accounts/AC.../Message/MM.../Media/ME557ce644e5ab84fa21cc21112e22c485 ``` ### Alternative: XML Appending ".xml" to the URI returns a familiar XML representation. For example: ```bash GET /2010-04-01/Accounts/AC.../Message/MM.../Media/ME557ce644e5ab84fa21cc21112e22c485.xml ``` ```xml ME557ce644e5ab84fa21cc21112e22c485 ACda6f1e11047ebd6fe7a55f120be3a900 MM8dfedb55c129dd4d6bd1f59af9d11080 image/jpeg Fri, 17 Jul 2009 01:52:49 +0000 Fri, 17 Jul 2009 01:52:49 +0000 /2010-04-01/Accounts/ACda6f1e11047ebd6fe7a55f120be3a900/Message/MM8dfedb55c129dd4d6bd1f59af9d11080/Media/ME557ce644e5ab84fa21cc21112e22c485.xml ``` ### Alternative: JSON Appending ".json" to the URI returns a familiar JSON representation. For example: ```bash GET /2010-04-01/Accounts/AC.../Message/MM.../Media/ME557ce644e5ab84fa21cc21112e22c485.json ``` ```javascript { "sid": "ME557ce644e5ab84fa21cc21112e22c485", "account_sid": "ACda6f1e11047ebd6fe7a55f120be3a900", "parent_sid": "MM8ff928b2451c0db925bd2d581f0fba79", "content_type": "image/jpeg", "date_created": "Fri, 26 Apr 2013 05:41:35 +0000", "date_updated": "Fri, 26 Apr 2013 05:41:35 +0000", "uri": "/2010-04-01/Accounts/ACda6f1e11047ebd6fe7a55f120be3a900/Message/MM8dfedb55c129dd4d6bd1f59af9d11080/Media/ME557ce644e5ab84fa21cc21112e22c485.json" } ``` ### Path parameters ```json [{"name":"AccountSid","in":"path","description":"The SID of the [Account](/docs/iam/api/account) associated with the Media resource.","schema":{"type":"string","minLength":34,"maxLength":34,"pattern":"^AC[0-9a-fA-F]{32}$"},"required":true},{"name":"MessageSid","in":"path","description":"The SID of the Message resource that is associated with the Media resource.","schema":{"type":"string","minLength":34,"maxLength":34,"pattern":"^(SM|MM)[0-9a-fA-F]{32}$"},"required":true},{"name":"Sid","in":"path","description":"The Twilio-provided string that uniquely identifies the Media resource to fetch.","schema":{"type":"string","minLength":34,"maxLength":34,"pattern":"^ME[0-9a-fA-F]{32}$"},"required":true}] ``` > \[!WARNING] > > Twilio enforces [HTTP Basic Authentication](/docs/glossary/what-is-basic-authentication) for all media URLs. Authenticate using an [API key](/docs/iam/api-keys) as the username and an API key secret as the password. You can also use your Account SID and Auth Token when testing locally. > > When you fetch your Message Media via the API, you will receive the media content directly. If you need to embed media in web applications without exposing your credentials, download the media files and serve them from your own server or cloud storage service. > > For applications that need temporary access to media URLs, consider implementing a server-side proxy that handles authentication and serves media to your client applications. Fetch a Medium ```ruby # Download the helper library from https://www.twilio.com/docs/ruby/install require 'twilio-ruby' # Find your Account SID and Auth Token at twilio.com/console # and set the environment variables. See http://twil.io/secure account_sid = ENV['TWILIO_ACCOUNT_SID'] auth_token = ENV['TWILIO_AUTH_TOKEN'] @client = Twilio::REST::Client.new(account_sid, auth_token) media = @client .api .v2010 .messages('SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa') .media('MEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa') .fetch puts media.account_sid ``` ```json { "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "content_type": "image/jpeg", "date_created": "Sun, 16 Aug 2015 15:53:54 +0000", "date_updated": "Sun, 16 Aug 2015 15:53:55 +0000", "parent_sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "sid": "MEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media/MEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json" } ``` ## Retrieve a list of Media `GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages/{MessageSid}/Media.json` Returns a list of Media associated with your Message. The list includes [paging information](/docs/usage/twilios-response#pagination). Retrieve a list of Media associated with a Message ```ruby # Download the helper library from https://www.twilio.com/docs/ruby/install require 'twilio-ruby' # Find your Account SID and Auth Token at twilio.com/console # and set the environment variables. See http://twil.io/secure account_sid = ENV['TWILIO_ACCOUNT_SID'] auth_token = ENV['TWILIO_AUTH_TOKEN'] @client = Twilio::REST::Client.new(account_sid, auth_token) media = @client .api .v2010 .messages('MMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX') .media .list(limit: 20) media.each do |record| puts record.account_sid end ``` ```json { "end": 0, "first_page_uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media.json?DateCreated%3E=2008-01-02&PageSize=50&Page=0", "media_list": [ { "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "content_type": "image/jpeg", "date_created": "Sun, 16 Aug 2015 15:53:54 +0000", "date_updated": "Sun, 16 Aug 2015 15:53:55 +0000", "parent_sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "sid": "MEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media/MEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json" } ], "next_page_uri": null, "page": 0, "page_size": 50, "previous_page_uri": null, "start": 0, "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media.json?DateCreated%3E=2008-01-02&PageSize=50&Page=0" } ``` ### Filter by date created You may limit the list of Message Media to media created on a given date. Provide the following query string parameter to your API call: ### Path parameters ```json [{"name":"AccountSid","in":"path","description":"The SID of the [Account](/docs/iam/api/account) that is associated with the Media resources.","schema":{"type":"string","minLength":34,"maxLength":34,"pattern":"^AC[0-9a-fA-F]{32}$"},"required":true},{"name":"MessageSid","in":"path","description":"The SID of the Message resource that is associated with the Media resources.","schema":{"type":"string","minLength":34,"maxLength":34,"pattern":"^(SM|MM)[0-9a-fA-F]{32}$"},"required":true}] ``` ### Query parameters ```json [{"name":"DateCreated","in":"query","description":"Only include Media resources that were created on this date. Specify a date as `YYYY-MM-DD` in GMT, for example: `2009-07-06`, to read Media that were created on this date. You can also specify an inequality, such as `StartTime<=YYYY-MM-DD`, to read Media that were created on or before midnight of this date, and `StartTime>=YYYY-MM-DD` to read Media that were created on or after midnight of this date.","schema":{"type":"string","format":"date-time"}},{"name":"DateCreated<","in":"query","description":"Only include Media resources that were created on this date. Specify a date as `YYYY-MM-DD` in GMT, for example: `2009-07-06`, to read Media that were created on this date. You can also specify an inequality, such as `StartTime<=YYYY-MM-DD`, to read Media that were created on or before midnight of this date, and `StartTime>=YYYY-MM-DD` to read Media that were created on or after midnight of this date.","schema":{"type":"string","format":"date-time"},"examples":{"readEmptyDatecreatedLess":{"value":"2008-01-02"}}},{"name":"DateCreated>","in":"query","description":"Only include Media resources that were created on this date. Specify a date as `YYYY-MM-DD` in GMT, for example: `2009-07-06`, to read Media that were created on this date. You can also specify an inequality, such as `StartTime<=YYYY-MM-DD`, to read Media that were created on or before midnight of this date, and `StartTime>=YYYY-MM-DD` to read Media that were created on or after midnight of this date.","schema":{"type":"string","format":"date-time"},"examples":{"readFull":{"value":"2008-01-02"}}},{"name":"PageSize","in":"query","description":"How many resources to return in each list page. The default is 50, and the maximum is 1000.","schema":{"type":"integer","format":"int64","minimum":1,"maximum":1000}},{"name":"Page","in":"query","description":"The page index. This value is simply for client state.","schema":{"type":"integer","minimum":0}},{"name":"PageToken","in":"query","description":"The page token. This is provided by the API.","schema":{"type":"string"}}] ``` ## Delete Media `DELETE https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages/{MessageSid}/Media/{Sid}.json` Deletes Media from your account. If successful, returns HTTP 204 (No Content) with no body. ### Path parameters ```json [{"name":"AccountSid","in":"path","description":"The SID of the [Account](/docs/iam/api/account) that is associated with the Media resource.","schema":{"type":"string","minLength":34,"maxLength":34,"pattern":"^AC[0-9a-fA-F]{32}$"},"required":true},{"name":"MessageSid","in":"path","description":"The SID of the Message resource that is associated with the Media resource.","schema":{"type":"string","minLength":34,"maxLength":34,"pattern":"^(SM|MM)[0-9a-fA-F]{32}$"},"required":true},{"name":"Sid","in":"path","description":"The unique identifier of the to-be-deleted Media resource.","schema":{"type":"string","minLength":34,"maxLength":34,"pattern":"^ME[0-9a-fA-F]{32}$"},"required":true}] ``` Delete Media from your account ```ruby # Download the helper library from https://www.twilio.com/docs/ruby/install require 'twilio-ruby' # Find your Account SID and Auth Token at twilio.com/console # and set the environment variables. See http://twil.io/secure account_sid = ENV['TWILIO_ACCOUNT_SID'] auth_token = ENV['TWILIO_AUTH_TOKEN'] @client = Twilio::REST::Client.new(account_sid, auth_token) @client .api .v2010 .messages('MM800f449d0399ed014aae2bcc0cc2f2ec') .media('ME557ce644e5ab84fa21cc21112e22c485') .delete ``` ### Hints and Advanced Uses \[#hints] * Twilio attempts to cache the media file the first time it is used. This may add a slight delay in sending the message. * Twilio caches files when HTTP headers allow it (via ETag and Last-Modified headers). Responding with `Cache-Control: no-cache` ensures Twilio always checks if the file has changed, allowing your web server to respond with a new version or with a 304 Not Modified to instruct Twilio to use its cached version.