> For the complete documentation index, see [llms.txt](https://docs.omnidesk.io/omnidesk/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.omnidesk.io/omnidesk/api-specification/email.md).

# Email

**All the endpoints that can be called on the Email controller.**

All these endpoints require the `SETTINGS_CRUD` permission, except for `GET` itemDownloadMail, which requires `TICKET_READ`

## newInboundMessage

> \*\*Creates a new inbound email message and decides if a new ticket is needed.\*\*\
> \
> If you want to add multiple items to a request, just copy the keys and add indices to the empty square brackets.

```json
{"openapi":"3.0.0","info":{"title":"Omnidesk API documentation","version":"1.0.0"},"tags":[{"name":"Email","description":"**All the endpoints that can be called on the Email controller.**\n\nAll these endpoints require the `SETTINGS_CRUD` permission, except for `GET` itemDownloadMail, which requires `TICKET_READ`"}],"servers":[{"url":"http://{{base_url}}"}],"security":[{"apikeyAuth":[]}],"components":{"securitySchemes":{"apikeyAuth":{"type":"http","scheme":"apikey"}}},"paths":{"/api/v2/email/newInboundMessage":{"post":{"tags":["Email"],"summary":"newInboundMessage","description":"**Creates a new inbound email message and decides if a new ticket is needed.**\n\nIf you want to add multiple items to a request, just copy the keys and add indices to the empty square brackets.","requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"messageID":{"type":"string","description":"type: `string` = ' '\n\nThe ID for the message to be created. Only used to check if the message exists already with this brand ID."},"externalID":{"type":"string","description":"type: `string` = ' '\n\nExternal ID of the ticket."},"fromAddress[name]":{"type":"string","description":"type: `string` = ' '\n\nThe name of where the email is being sent from."},"fromAddress[address]":{"type":"string","description":"type: `string` = ' '\n\nThe address where the email is being sent from."},"replyToAddress[name]":{"type":"string","description":"type: `string` = ' '\n\nAlternative to fromAddress[name] if it is a reply."},"replyToAddress[address]":{"type":"string","description":"type: `string` = ' '\n\nAlternative to fromAddress[address] if it is a reply."},"toAddresses[][address]":{"type":"string","description":"type: `string`\n\nThe address where this message is being sent to."},"ccAddresses[][address]":{"type":"string","description":"type: `string` = null\n\nThe CC address where this message is being sent to."},"bccAddresses[][address]":{"type":"string","description":"type: `string` = null\n\nThe BCC address where this message is being sent to."},"subject":{"type":"string","description":"type: `string` = null\n\nThe subject of the message."},"htmlBody":{"type":"string","description":"type: `string` = null\n\nThe HTML body of this message. If you use this one, do not use plainTextBody as well."},"plainTextBody":{"type":"string","description":"type: `string` = null\n\nThe plain text body of this message. If you use this one, do not use htmlBody as well."},"references[]":{"type":"string","description":"type: `string` = null\n\nUse this if you want to reply to a thread as to make sure the application does not create a new ticket."},"attachmentsBase64[0][fileCID]":{"type":"string","description":"type: `string` = null"},"attachmentsBase64[0][fileName]":{"type":"string","description":"type: `string` = null"},"attachmentsBase64[0][fileType]":{"type":"string","description":"type: `string` = null"},"attachmentsBase64[0][fileExtension]":{"type":"string","description":"type: `string` = null"},"attachmentsBase64[0][fileBase64Content]":{"type":"string","description":"type: `string` = null"}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{}}}}}}}}
```

## address

> \*\*Returns all email addresses with optional filters such as search queries, grouping and result limits.\*\*

```json
{"openapi":"3.0.0","info":{"title":"Omnidesk API documentation","version":"1.0.0"},"tags":[{"name":"Email","description":"**All the endpoints that can be called on the Email controller.**\n\nAll these endpoints require the `SETTINGS_CRUD` permission, except for `GET` itemDownloadMail, which requires `TICKET_READ`"}],"servers":[{"url":"http://{{base_url}}"}],"security":[{"apikeyAuth":[]}],"components":{"securitySchemes":{"apikeyAuth":{"type":"http","scheme":"apikey"}}},"paths":{"/api/v2/email/address":{"get":{"tags":["Email"],"summary":"address","description":"**Returns all email addresses with optional filters such as search queries, grouping and result limits.**","responses":{"200":{"description":"Successful response","content":{"application/json":{}}}}}}}}
```

## address

> \*\*Creates a new email address.\*\*

```json
{"openapi":"3.0.0","info":{"title":"Omnidesk API documentation","version":"1.0.0"},"tags":[{"name":"Email","description":"**All the endpoints that can be called on the Email controller.**\n\nAll these endpoints require the `SETTINGS_CRUD` permission, except for `GET` itemDownloadMail, which requires `TICKET_READ`"}],"servers":[{"url":"http://{{base_url}}"}],"security":[{"apikeyAuth":[]}],"components":{"securitySchemes":{"apikeyAuth":{"type":"http","scheme":"apikey"}}},"paths":{"/api/v2/email/address":{"post":{"tags":["Email"],"summary":"address","description":"**Creates a new email address.**","requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"brand_id":{"type":"string","description":"type: `number`"},"email":{"type":"string","description":"type: `string`\n\nHas to be a valid email address format."},"reply_email":{"type":"string","description":"type: `string`\n\nHas to be a valid email address format."},"reply_email_title":{"type":"string","description":"type: `^[a-zA-ZÀ-ÖØ-Þß-öø-ÿŠš\\.\\-\\', ]+$` = null"},"is_primary":{"type":"string","description":"type: `^[0,1]$`"},"signature":{"type":"string","description":"type: `string` = ' '"},"group_id":{"type":"string","description":"type: `number` = 0"}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{}}}}}}}}
```

## itemAddress

> \*\*Returns this specific email address.\*\*

```json
{"openapi":"3.0.0","info":{"title":"Omnidesk API documentation","version":"1.0.0"},"tags":[{"name":"Email","description":"**All the endpoints that can be called on the Email controller.**\n\nAll these endpoints require the `SETTINGS_CRUD` permission, except for `GET` itemDownloadMail, which requires `TICKET_READ`"}],"servers":[{"url":"http://{{base_url}}"}],"security":[{"apikeyAuth":[]}],"components":{"securitySchemes":{"apikeyAuth":{"type":"http","scheme":"apikey"}}},"paths":{"/api/v2/email/address/{id}":{"get":{"tags":["Email"],"summary":"itemAddress","description":"**Returns this specific email address.**","parameters":[{"name":"id","in":"path","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{}}}}}}}}
```

## itemAddress

> \*\*Updates this specific email address.\*\*

```json
{"openapi":"3.0.0","info":{"title":"Omnidesk API documentation","version":"1.0.0"},"tags":[{"name":"Email","description":"**All the endpoints that can be called on the Email controller.**\n\nAll these endpoints require the `SETTINGS_CRUD` permission, except for `GET` itemDownloadMail, which requires `TICKET_READ`"}],"servers":[{"url":"http://{{base_url}}"}],"security":[{"apikeyAuth":[]}],"components":{"securitySchemes":{"apikeyAuth":{"type":"http","scheme":"apikey"}}},"paths":{"/api/v2/email/address/{id}":{"put":{"tags":["Email"],"summary":"itemAddress","description":"**Updates this specific email address.**","requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"properties":{"group_id":{"type":"string","description":"type: `number` = 0"},"brand_id":{"type":"string","description":"type: `number`"},"email":{"type":"string","description":"type: `string`\n\nHas to be a valid email address format."},"reply_email":{"type":"string","description":"type: `string`\n\nHas to be a valid email address format."},"reply_email_title":{"type":"string","description":"type: `^[a-zA-ZÀ-ÖØ-Þß-öø-ÿŠš\\.\\-\\', ]+$` = null"},"is_primary":{"type":"string","description":"type: `^[0,1]$`"},"group_by_time":{"type":"string","description":"type: `number` = 0"},"group_by_time_amount":{"type":"string","description":"type: `number` = 0"},"signature":{"type":"string","description":"type: `string` = ' '"}}}}}},"parameters":[{"name":"id","in":"path","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{}}}}}}}}
```

## itemAddress

> \*\*Permanently deletes this specific email address.\*\*

```json
{"openapi":"3.0.0","info":{"title":"Omnidesk API documentation","version":"1.0.0"},"tags":[{"name":"Email","description":"**All the endpoints that can be called on the Email controller.**\n\nAll these endpoints require the `SETTINGS_CRUD` permission, except for `GET` itemDownloadMail, which requires `TICKET_READ`"}],"servers":[{"url":"http://{{base_url}}"}],"security":[{"apikeyAuth":[]}],"components":{"securitySchemes":{"apikeyAuth":{"type":"http","scheme":"apikey"}}},"paths":{"/api/v2/email/address/{id}":{"delete":{"tags":["Email"],"summary":"itemAddress","description":"**Permanently deletes this specific email address.**","parameters":[{"name":"id","in":"path","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{}}}}}}}}
```

## itemDownloadMail

> \*\*Downloads a specific email based on its message ID.\*\*

```json
{"openapi":"3.0.0","info":{"title":"Omnidesk API documentation","version":"1.0.0"},"tags":[{"name":"Email","description":"**All the endpoints that can be called on the Email controller.**\n\nAll these endpoints require the `SETTINGS_CRUD` permission, except for `GET` itemDownloadMail, which requires `TICKET_READ`"}],"servers":[{"url":"http://{{base_url}}"}],"security":[{"apikeyAuth":[]}],"components":{"securitySchemes":{"apikeyAuth":{"type":"http","scheme":"apikey"}}},"paths":{"/api/v2/email/downloadMail/{id}":{"get":{"tags":["Email"],"summary":"itemDownloadMail","description":"**Downloads a specific email based on its message ID.**","parameters":[{"name":"id","in":"path","schema":{"type":"string"},"required":true,"description":"ID of the message to download."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{}}}}}}}}
```