# Voicemails
Manage voicemail functions.
## List voicemails
> Retrieve a collection of voicemails.
```json
{"openapi":"3.1.0","info":{"title":"PortSIP PBX Rest API","version":"22.3"},"tags":[{"name":"Voicemail","description":"Manage voicemail functions.\n"}],"servers":[{"url":"{protocol}://{hostname}:{port}/api","variables":{"protocol":{"description":"Self-hosted Enterprise Server protocol.","default":"https"},"hostname":{"description":"Self-hosted Enterprise Server hostname.","default":"HOSTNAME"},"port":{"description":"Self-hosted Enterprise Server port.","default":"8887"}}}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer"}}},"paths":{"/voicemails":{"get":{"tags":["Voicemail"],"operationId":"listVoicemails","summary":"List voicemails","description":"Retrieve a collection of voicemails.\n","parameters":[{"name":"filter","in":"query","required":false,"schema":{"type":"string"},"description":"Use the `filter` query parameter to retrieve just a subset of a collection.\n"},{"name":"search","in":"query","required":false,"schema":{"type":"string"},"description":"Use the `search` query parameter to restrict the results of a request to match a search criterion.\n"},{"name":"orderby","in":"query","required":false,"schema":{"type":"string"},"description":"Use the `orderby` query parameter to specify the sort order of the items returned from server. \nThe default order is ascending order.\n"},{"name":"skip","in":"query","required":false,"schema":{"type":"integer","format":"int32","minimum":0,"default":0},"description":"Use the `skip` query parameter to set the number of items to skip at the start of a collection.\n"},{"name":"top","in":"query","required":false,"schema":{"type":"integer","format":"int32","minimum":1,"maximum":100,"default":100},"description":"Use the `top` query parameter to specify the page size of the result set.\n"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer","format":"int64","minimum":0,"description":"Total number of resource.\n"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"allOf":[{"type":"string","description":"The unique ID of the resource.\n"}],"description":"The unique ID of voicemail.\n"},"sender":{"type":"string","description":"The sender number of the voicemail.\n"},"created_at":{"allOf":[{"type":"string","format":"date_time","description":"The RFC 3339 format is defined by\nThe date_time notation as defined by [RFC 3339, section 5.6](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), \nfor example, 2017-07-21T17:32:28Z\n"}],"description":"The creation time of voicemail.\n"},"duration":{"type":"integer","format":"int32","description":"The playback time (in seconds).\n"},"status":{"type":"string","enum":["READ","UNREAD"],"description":"Status of the voicemail includes:\n- `READ`: read mail\n- `UNREAD`: unread mail\n"},"file_name":{"type":"string","description":"The name of the file.\n"},"file_size":{"type":"integer","format":"int64","minimum":0,"description":"The file size in bytes.\n"},"file_url":{"type":"string","readOnly":true,"description":"The relative path to file url for file downloading.\n"},"transcription_status":{"type":"string","description":"AI transcription status.\n- TranscriptionNotStarted\n- TranscriptionQuotaLimited\n- TranscriptionRunning\n- TranscriptionFailed\n- TranscriptionSucceeded\n- AnalyzeRunning\n- AnalyzeFailed\n- AnalyzeSucceeded\n- TranscriptionUploadFailed\n- TranscriptionOtherFailed\n","enum":["TRANSCRIPTION_NOTSTARTED","TRANSCRIPTION_QUOTALIMITED","TRANSCRIPTION_RUNNING","TRANSCRIPTION_FAILED","TRANSCRIPTION_SUCCEEDED","ANALYZE_RUNNING","ANALYZE_FAILED","ANALYZE_SUCCEEDED","TRANSCRIPTION_UPLOAD_FAILED","TRANSCRIPTION_OTHER_FAILED"]},"transcription_status_desc":{"type":"string","description":"AI transcription status description."},"transcription_sentiment":{"type":"string","description":"AI transcription sentiment.\n- SentimentPositive\n- SentimentNeutral\n- SentimentNegative\n","enum":["SENTIMENT_POSITIVE","SENTIMENT_NEUTRAL","SENTIMENT_NEGATIVE"]}}}}}}}}},"4XX":{"description":"Error"}}}}}}
```
## Retrieve a voicemail
> Retrieve voicemail information.
```json
{"openapi":"3.1.0","info":{"title":"PortSIP PBX Rest API","version":"22.3"},"tags":[{"name":"Voicemail","description":"Manage voicemail functions.\n"}],"servers":[{"url":"{protocol}://{hostname}:{port}/api","variables":{"protocol":{"description":"Self-hosted Enterprise Server protocol.","default":"https"},"hostname":{"description":"Self-hosted Enterprise Server hostname.","default":"HOSTNAME"},"port":{"description":"Self-hosted Enterprise Server port.","default":"8887"}}}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer"}}},"paths":{"/voicemails/{id}":{"get":{"tags":["Voicemail"],"operationId":"showVoicemail","summary":"Retrieve a voicemail","description":"Retrieve voicemail information.\n","parameters":[{"name":"id","in":"path","required":true,"schema":{"allOf":[{"type":"string","description":"The unique ID of the resource.\n"}],"description":"The unique ID of voicemail.\n"},"description":"The unique ID of voicemail."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"allOf":[{"type":"string","description":"The unique ID of the resource.\n"}],"description":"The unique ID of voicemail.\n"},"sender":{"type":"string","description":"The sender number of the voicemail.\n"},"created_at":{"allOf":[{"type":"string","format":"date_time","description":"The RFC 3339 format is defined by\nThe date_time notation as defined by [RFC 3339, section 5.6](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), \nfor example, 2017-07-21T17:32:28Z\n"}],"description":"The creation time of voicemail.\n"},"duration":{"type":"integer","format":"int32","description":"The playback time (in seconds).\n"},"status":{"type":"string","enum":["READ","UNREAD"],"description":"Status of the voicemail includes:\n- `READ`: read mail\n- `UNREAD`: unread mail\n"},"file_name":{"type":"string","description":"The name of the file.\n"},"file_size":{"type":"integer","format":"int64","minimum":0,"description":"The file size in bytes.\n"},"file_url":{"type":"string","readOnly":true,"description":"The relative path to file url for file downloading.\n"}}}}}},"4XX":{"description":"Error"}}}}}}
```
## Update voicemail status to read
> Update voicemail status to read
```json
{"openapi":"3.1.0","info":{"title":"PortSIP PBX Rest API","version":"22.3"},"tags":[{"name":"Voicemail","description":"Manage voicemail functions.\n"}],"servers":[{"url":"{protocol}://{hostname}:{port}/api","variables":{"protocol":{"description":"Self-hosted Enterprise Server protocol.","default":"https"},"hostname":{"description":"Self-hosted Enterprise Server hostname.","default":"HOSTNAME"},"port":{"description":"Self-hosted Enterprise Server port.","default":"8887"}}}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer"}}},"paths":{"/voicemails/{id}/set_read":{"post":{"tags":["Voicemail"],"operationId":"setVoicemailRead","summary":"Update voicemail status to read","description":"Update voicemail status to read\n","parameters":[{"name":"id","in":"path","required":true,"schema":{"allOf":[{"type":"string","description":"The unique ID of the resource.\n"}],"description":"The unique ID of voicemail.\n"},"description":"The unique ID of voicemail."}],"responses":{"200":{"description":"OK"},"400":{"description":"Invalid voicemail ID supplied"}}}}}}
```
## Update voicemail status to unread
> Update voicemail status to unread
```json
{"openapi":"3.1.0","info":{"title":"PortSIP PBX Rest API","version":"22.3"},"tags":[{"name":"Voicemail","description":"Manage voicemail functions.\n"}],"servers":[{"url":"{protocol}://{hostname}:{port}/api","variables":{"protocol":{"description":"Self-hosted Enterprise Server protocol.","default":"https"},"hostname":{"description":"Self-hosted Enterprise Server hostname.","default":"HOSTNAME"},"port":{"description":"Self-hosted Enterprise Server port.","default":"8887"}}}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer"}}},"paths":{"/voicemails/{id}/set_unread":{"post":{"tags":["Voicemail"],"operationId":"setVoicemailUnRead","summary":"Update voicemail status to unread","description":"Update voicemail status to unread\n","parameters":[{"name":"id","in":"path","required":true,"schema":{"allOf":[{"type":"string","description":"The unique ID of the resource.\n"}],"description":"The unique ID of voicemail.\n"},"description":"The unique ID of voicemail."}],"responses":{"200":{"description":"OK"},"400":{"description":"Invalid voicemail ID supplied"}}}}}}
```
## POST /voicemails/{id}/destroy
> Delete a voicemail
```json
{"openapi":"3.1.0","info":{"title":"PortSIP PBX Rest API","version":"22.3"},"tags":[{"name":"Voicemail","description":"Manage voicemail functions.\n"}],"servers":[{"url":"{protocol}://{hostname}:{port}/api","variables":{"protocol":{"description":"Self-hosted Enterprise Server protocol.","default":"https"},"hostname":{"description":"Self-hosted Enterprise Server hostname.","default":"HOSTNAME"},"port":{"description":"Self-hosted Enterprise Server port.","default":"8887"}}}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer"}}},"paths":{"/voicemails/{id}/destroy":{"post":{"tags":["Voicemail"],"operationId":"deleteVoicemail","summary":"Delete a voicemail","parameters":[{"name":"id","in":"path","required":true,"schema":{"allOf":[{"type":"string","description":"The unique ID of the resource.\n"}],"description":"The unique ID of voicemail.\n"},"description":"The unique ID of the voicemail."}],"responses":{"204":{"description":"No Content"},"400":{"description":"Invalid voicemail ID supplied"},"404":{"description":"User not found"}}}}}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://support.portsip.com/development-portsip/rest-apis/version-22.3/voicemails.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.