ImmobiNet
ImmobiNet API Docs - Messages

Retrieve messages

GET
/api/v1/messages
basic

Returns a paginated list of messages filtered by provided parameters. Default order is by created_at in descending order. Requires the API key scope messages:read.

Retrieve messages › query Parameters

context
​string · enum

Context to filter messages by

Enum values:
reservation
quote
context_id
​string

ID of the context to filter messages by

transport
​string · enum

Transport used to send the message

Enum values:
airbnb
sms
email
time_field
​string · enum

Time field the from/to filter applies to. Required when from or to is present.

Enum values:
sent_at
last_read_at
created_at
from
​string · date-time

Lower bound of the time_field filter. Europe/Rome timezone, RFC 3339 format (e.g. 2026-06-26T00:00:00+02:00)

to
​string · date-time

Upper bound of the time_field filter. Europe/Rome timezone, RFC 3339 format (e.g. 2026-06-26T23:59:59+02:00)

sort_field
​string · enum

Sort column. With sent_at only the messages that have been sent are listed (a draft has no sent time). Keep the same sort_field on every page of a read: a next_cursor obtained with one sort field returns 400 with another.

Enum values:
created_at
sent_at
sort_order
​string · enum

If sort_field is specified but sort_order is not, the default order is 'asc'

Enum values:
asc
desc
paging_limit
​integer · min: 1 · max: 50

Limit items returned in response. Must be between 1 and 50

Default: 20
next_cursor
​string | null

Retrieve messages › Responses

Successful response

​object
​Message[]

Retrieve a single message

GET
/api/v1/messages/{messageId}
basic

Requires the API key scope messages:read.

Retrieve a single message › path Parameters

messageId
​integer · required

Retrieve a single message › Responses

Message found

id
​integer
status
​string · enum
Enum values:
draft
queued
sent
failed
created_at
​string · date-time

Message creation time.

Example: 2026-06-26T14:30:00+02:00
subject
​string | null
​MessageMessage
transport
​string · enum
Enum values:
airbnb
sms
email
direction
​string · enum
Enum values:
inbound
outbound
​MessageContact | null
​MessageContact[]
sent_at
​string · date-time

Message send time.

Example: 2026-06-26T14:30:00+02:00
last_read_at
​DatetimeRome | null · date-time

Last read time.

Example: 2026-06-26T14:30:00+02:00
reads
​array | null

Every time the message was read, in ascending order (the last one is last_read_at). Only in the detail of a message (GET /api/v1/messages/{messageId}), null everywhere else (the list and the replies) because reading it costs a query per message. An empty list when the message was never read.

language
​LanguageCode | null · pattern: ^[a-z]{2}$

Language of the first recipient. null if not set.

Example: it
​MessageReferences
​MessageAttachment[]

Create a draft reply to a message

POST
/api/v1/messages/{messageId}
basic

Creates a draft reply to an existing message. The draft is saved with status: draft and is not sent. To attach files use POST /api/v1/messages/{messageId}/attachments (messageId here is the id of the draft returned by this call, not the original message), to remove one use DELETE /api/v1/messages/{messageId}/attachments/{fileName}, and to actually send the draft use POST /api/v1/messages/{messageId}/send. Before sending, the draft's subject/message can be amended with PATCH /api/v1/messages/{messageId}. Requires the API key scope messages:write.

Create a draft reply to a message › path Parameters

messageId
​integer · required

Create a draft reply to a message › Request Body

​MessageMessage · required
subject
​string

Required if is an email message

Create a draft reply to a message › Responses

Draft created

id
​integer
status
​string · enum
Enum values:
draft
queued
sent
failed
created_at
​string · date-time

Message creation time.

Example: 2026-06-26T14:30:00+02:00
subject
​string | null
​MessageMessage
transport
​string · enum
Enum values:
airbnb
sms
email
direction
​string · enum
Enum values:
inbound
outbound
​MessageContact | null
​MessageContact[]
sent_at
​string · date-time

Message send time.

Example: 2026-06-26T14:30:00+02:00
last_read_at
​DatetimeRome | null · date-time

Last read time.

Example: 2026-06-26T14:30:00+02:00
reads
​array | null

Every time the message was read, in ascending order (the last one is last_read_at). Only in the detail of a message (GET /api/v1/messages/{messageId}), null everywhere else (the list and the replies) because reading it costs a query per message. An empty list when the message was never read.

language
​LanguageCode | null · pattern: ^[a-z]{2}$

Language of the first recipient. null if not set.

Example: it
​MessageReferences
​MessageAttachment[]

Amend a draft reply

PATCH
/api/v1/messages/{messageId}
basic

Updates subject/message of a reply that is still in draft status. Requires the API key scope messages:write.

Amend a draft reply › path Parameters

messageId
​integer · required

Amend a draft reply › Request Body

subject
​string

Required if is an email message

​MessageMessage

Amend a draft reply › Responses

Draft updated

id
​integer
status
​string · enum
Enum values:
draft
queued
sent
failed
created_at
​string · date-time

Message creation time.

Example: 2026-06-26T14:30:00+02:00
subject
​string | null
​MessageMessage
transport
​string · enum
Enum values:
airbnb
sms
email
direction
​string · enum
Enum values:
inbound
outbound
​MessageContact | null
​MessageContact[]
sent_at
​string · date-time

Message send time.

Example: 2026-06-26T14:30:00+02:00
last_read_at
​DatetimeRome | null · date-time

Last read time.

Example: 2026-06-26T14:30:00+02:00
reads
​array | null

Every time the message was read, in ascending order (the last one is last_read_at). Only in the detail of a message (GET /api/v1/messages/{messageId}), null everywhere else (the list and the replies) because reading it costs a query per message. An empty list when the message was never read.

language
​LanguageCode | null · pattern: ^[a-z]{2}$

Language of the first recipient. null if not set.

Example: it
​MessageReferences
​MessageAttachment[]

Delete a draft reply

DELETE
/api/v1/messages/{messageId}
basic

Deletes a reply that is still in draft status, together with any attachments uploaded to it. Requires the API key scope messages:delete.

Delete a draft reply › path Parameters

messageId
​integer · required

Delete a draft reply › Responses

Draft deleted


Upload an attachment to a draft reply

POST
/api/v1/messages/{messageId}/attachments
basic

Uploads one file to a reply that is still in draft status. One file per call. Attachment rules depend on the transport of the original message:

TransportAttachments allowedAccepted MIME typesSize limit
smsNo——
emailYesimage/png, image/jpeg, image/gif, application/pdfTotal ≤ 10 MB (all attachments of the draft combined)
airbnbYesimage/png, image/jpeg, image/gifEach file ≤ 5 MB

If an attachment with the same file name already exists on the draft, the uploaded file is renamed (e.g. photo-1.jpg) — the client must read the actual name back from the response. Requires the API key scope messages:write.

Upload an attachment to a draft reply › path Parameters

messageId
​integer · required

Upload an attachment to a draft reply › Request Body

file
​binary · application/octet-stream · required

Upload an attachment to a draft reply › Responses

Attachment uploaded

name
​string
url
​string · uri
mime_type
​string

Remove an attachment from a draft reply

DELETE
/api/v1/messages/{messageId}/attachments/{fileName}
basic

Removes a file previously uploaded to a reply that is still in draft status. Requires the API key scope messages:delete.

Remove an attachment from a draft reply › path Parameters

messageId
​integer · required
fileName
​string · pattern: .+ · required

Must be URL-encoded, since the original file name may contain characters not valid in a path segment (spaces, %, non-ASCII, etc.). Cannot contain < > : " / \ | ? * (invalid in file names) or control characters.

Remove an attachment from a draft reply › Responses

Attachment removed


Send a draft reply

POST
/api/v1/messages/{messageId}/send
basic

Queues a reply that is in draft status for sending. This call is asynchronous: it moves the draft to status: queued and returns immediately, the actual delivery through the transport happens afterwards. Returns 409 if the message is not currently in draft status (for example it was already sent).

For the airbnb transport, text and media cannot be sent together: if the draft has attachments, the message text and each attachment are delivered as separate messages on the conversation thread, text first. Requires the API key scope messages:send.

Send a draft reply › path Parameters

messageId
​integer · required

Send a draft reply › Responses

Message queued for send

id
​integer
status
​string · enum
Enum values:
draft
queued
sent
failed
created_at
​string · date-time

Message creation time.

Example: 2026-06-26T14:30:00+02:00
subject
​string | null
​MessageMessage
transport
​string · enum
Enum values:
airbnb
sms
email
direction
​string · enum
Enum values:
inbound
outbound
​MessageContact | null
​MessageContact[]
sent_at
​string · date-time

Message send time.

Example: 2026-06-26T14:30:00+02:00
last_read_at
​DatetimeRome | null · date-time

Last read time.

Example: 2026-06-26T14:30:00+02:00
reads
​array | null

Every time the message was read, in ascending order (the last one is last_read_at). Only in the detail of a message (GET /api/v1/messages/{messageId}), null everywhere else (the list and the replies) because reading it costs a query per message. An empty list when the message was never read.

language
​LanguageCode | null · pattern: ^[a-z]{2}$

Language of the first recipient. null if not set.

Example: it
​MessageReferences
​MessageAttachment[]