# 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":{}}}}}}}}
```


---

# 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://docs.omnidesk.io/omnidesk/api-specification/email.md?ask=<question>
```

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.