API docs by Redocly

message API (develop:84871a)

Download OpenAPI specification:

License: None

Automatically generated swagger spec for the message stack.

MailService

Activate mailboxes

Activates the mailboxes identified by the given IDs.

Request Body schema: application/json
required
ids
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{ }

Add confidential emails

Adds email addresses to the confidential email list for the given account.

Request Body schema: application/json
required
accountId
required
string <int64>
emails
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "accountId": "string",
  • "emails": [
    ]
}

Response samples

Content type
application/json
{ }

Archive mails

Archives the mails identified by the given IDs.

Request Body schema: application/json
required
ids
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{ }

Bulk send mails

Sends multiple mails in one request using the provided entries (owner, participants, subject, body, attachments, and optional reply/confidential settings). Returns the sent mails.

Request Body schema: application/json
required
required
Array of objects (v2BulkSendMailEntry)

Responses

Request samples

Content type
application/json
{
  • "entries": [
    ]
}

Response samples

Content type
application/json
{
  • "mail": [
    ]
}

Count mail drafts

Returns the number of mail drafts for the authenticated caller. The request has no parameters.

Responses

Response samples

Content type
application/json
{
  • "amount": 0
}

Count unread mails

Returns the number of unread mails across the given mailbox IDs.

path Parameters
mailboxIds
required
Array of strings non-empty

Responses

Response samples

Content type
application/json
{
  • "count": 0
}

Create a mail domain

Creates a new mail domain for the given owner. Returns the created domain including its validation key.

Request Body schema: application/json
required
domain
required
string
ownerId
required
string <int64>

Responses

Request samples

Content type
application/json
{
  • "domain": "string",
  • "ownerId": "string"
}

Response samples

Content type
application/json
{
  • "domain": {
    }
}

Create a mailbox

Creates a new mailbox for the given owner. Accepts mailbox type, outbound email, name, optional main and allowed user IDs, and an optional signature ID. Returns the created mailbox.

Request Body schema: application/json
required
allowedUserIds
required
Array of strings
mailboxType
required
string (v2MailboxType)
Default: "MAILBOX_TYPE_SPF"
Enum: "MAILBOX_TYPE_SPF" "MAILBOX_TYPE_NYLAS" "MAILBOX_TYPE_NYLAS_MANUAL"
mainUserId
required
string (Can be empty if no specific user is using this mailbox)
name
required
string
outboundEmail
required
string
ownerId
required
string <int64>
signatureId
required
string

Responses

Request samples

Content type
application/json
{
  • "allowedUserIds": [
    ],
  • "mailboxType": "MAILBOX_TYPE_SPF",
  • "mainUserId": "string",
  • "name": "string",
  • "outboundEmail": "string",
  • "ownerId": "string",
  • "signatureId": "string"
}

Response samples

Content type
application/json
{
  • "mailbox": {
    }
}

Deactivate mailboxes

Deactivates the mailboxes identified by the given IDs.

Request Body schema: application/json
required
ids
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{ }

Delete a mail domain

Deletes the mail domain identified by the given ID.

path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{ }

Delete mail drafts

Deletes the mail drafts identified by the given IDs.

path Parameters
ids
required
Array of strings non-empty

Responses

Response samples

Content type
application/json
{ }

Delete mails

Permanently deletes the mails identified by the given IDs.

path Parameters
ids
required
Array of strings non-empty

Responses

Response samples

Content type
application/json
{ }

Edit a mailbox

Updates an existing mailbox by ID, including outbound email, name, main and allowed user IDs, and signature ID.

path Parameters
id
required
string
Request Body schema: application/json
required
allowedUserIds
Array of strings
mainUserId
string (Can be empty if no specific user is using this mailbox)
name
string
outboundEmail
string
signatureId
string

Responses

Request samples

Content type
application/json
{
  • "allowedUserIds": [
    ],
  • "mainUserId": "string",
  • "name": "string",
  • "outboundEmail": "string",
  • "signatureId": "string"
}

Response samples

Content type
application/json
{ }

Forward a mail

Forwards an existing mail identified by forwardingMailId to the given recipients. Accepts owner, participants, subject, body, attachments, and a confidential flag. Returns the forwarded mail.

Request Body schema: application/json
required
attachmentMediaIds
required
Array of strings
required
Array of objects (mailv2Participant)
bodyHtml
required
string
bodyText
required
string
required
Array of objects (mailv2Participant)
confidential
required
boolean
forwardingMailId
required
string
required
object (mailv2Participant)
ownerId
required
string <int64>
referenceIds
required
Array of strings
subject
required
string
required
Array of objects (mailv2Participant)

Responses

Request samples

Content type
application/json
{
  • "attachmentMediaIds": [
    ],
  • "bcc": [
    ],
  • "bodyHtml": "string",
  • "bodyText": "string",
  • "cc": [
    ],
  • "confidential": true,
  • "forwardingMailId": "string",
  • "from": {
    },
  • "ownerId": "string",
  • "referenceIds": [
    ],
  • "subject": "string",
  • "to": [
    ]
}

Response samples

Content type
application/json
{
  • "mail": {
    }
}

Get delivery and engagement data

Returns delivery and engagement data for mails matching the given reference IDs, including participants, deliverability status, engagement status, and timestamps.

Request Body schema: application/json
required
referenceIds
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "referenceIds": [
    ]
}

Response samples

Content type
application/json
{
  • "entries": [
    ]
}

Get a mailbox

Returns the mailbox identified by the given ID.

path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "mailbox": {
    }
}

Check domain dedicated IP

Returns whether the domain of the given from-email address has a dedicated IP.

query Parameters
fromEmail
string

Responses

Response samples

Content type
application/json
{
  • "hasDedicated": true
}

List confidential emails

Returns the confidential email addresses registered for the given account.

path Parameters
accountId
required
string <int64>

Responses

Response samples

Content type
application/json
{
  • "emails": [
    ]
}

List mail domains for an owner

Returns all mail domains belonging to the given owner.

path Parameters
ownerId
required
string <int64>

Responses

Response samples

Content type
application/json
{
  • "domains": [
    ]
}

List mail drafts

Returns all mail drafts for the authenticated caller. The request has no parameters.

Responses

Response samples

Content type
application/json
{
  • "drafts": [
    ]
}

List latest mails for reference IDs

Returns the latest mail for each of the given reference IDs.

Request Body schema: application/json
required
referenceIds
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "referenceIds": [
    ]
}

Response samples

Content type
application/json
{
  • "mails": [
    ]
}

List mail IDs in mailboxes

Returns mail IDs for the given mailbox IDs. Supports query text, unread and folder filters, reference-ID prefix exclusions, and sorting by received time.

Request Body schema: application/json
required
filterFolder
required
string (v2FilterFolder)
Default: "FILTER_FOLDER_ALL"
Enum: "FILTER_FOLDER_ALL" "FILTER_FOLDER_INBOUND" "FILTER_FOLDER_OUTBOUND" "FILTER_FOLDER_ARCHIVED" "FILTER_FOLDER_TRASH" "FILTER_FOLDER_SPAM"
filterReferenceIdPrefixes
required
Array of strings

All mails with provided entity prefixes in referenceIds are excluded from results

filterUnread
required
string (applicableApplicable)
Default: "UNDEFINED_VALUE"
Enum: "UNDEFINED_VALUE" "APPLIES" "DOES_NOT_APPLY"
mailboxIds
required
Array of strings
query
required
string
sortReceivedAt
required
string (sortSortOrder)
Default: "UNDEFINED_SORT_ORDER"
Enum: "UNDEFINED_SORT_ORDER" "ASC" "DESC"

Responses

Request samples

Content type
application/json
{
  • "filterFolder": "FILTER_FOLDER_ALL",
  • "filterReferenceIdPrefixes": [
    ],
  • "filterUnread": "UNDEFINED_VALUE",
  • "mailboxIds": [
    ],
  • "query": "string",
  • "sortReceivedAt": "UNDEFINED_SORT_ORDER"
}

Response samples

Content type
application/json
{
  • "ids": [
    ]
}

List mailboxes by account ID

Returns all mailboxes belonging to the given account ID.

path Parameters
accountId
required
string <int64>

Responses

Response samples

Content type
application/json
{
  • "mailboxes": [
    ]
}

List mailboxes by user ID

Returns all mailboxes accessible to the given user ID.

path Parameters
userId
required
string

Responses

Response samples

Content type
application/json
{
  • "mailboxes": [
    ]
}

List mails in mailboxes

Returns a paginated list of mails for the given mailbox IDs. Supports query text, unread and folder filters, reference-ID prefix exclusions, and sorting by received time. Optional limitPagination can cap exact counts for performance. Response includes total and page counts.

Request Body schema: application/json
required
filterFolder
required
string (v2FilterFolder)
Default: "FILTER_FOLDER_ALL"
Enum: "FILTER_FOLDER_ALL" "FILTER_FOLDER_INBOUND" "FILTER_FOLDER_OUTBOUND" "FILTER_FOLDER_ARCHIVED" "FILTER_FOLDER_TRASH" "FILTER_FOLDER_SPAM"
filterReferenceIdPrefixes
required
Array of strings (All mails with provided entity prefixes in referenceIds are excluded from results)

All mails with provided entity prefixes in referenceIds are excluded from results

filterUnread
required
string (applicableApplicable)
Default: "UNDEFINED_VALUE"
Enum: "UNDEFINED_VALUE" "APPLIES" "DOES_NOT_APPLY"
itemsPerPage
required
integer <int32>
limitPagination
required
boolean

If set to true, the response will only contain exact count until 100 mails. Page count won't be accurate after that. This flag can be used for performance reasons.

mailboxIds
required
Array of strings
page
required
integer <int32>
query
required
string
sortFromEmail
required
string (sortSortOrder)
Default: "UNDEFINED_SORT_ORDER"
Enum: "UNDEFINED_SORT_ORDER" "ASC" "DESC"
sortReceivedAt
required
string (sortSortOrder)
Default: "UNDEFINED_SORT_ORDER"
Enum: "UNDEFINED_SORT_ORDER" "ASC" "DESC"

Responses

Request samples

Content type
application/json
{
  • "filterFolder": "FILTER_FOLDER_ALL",
  • "filterReferenceIdPrefixes": [
    ],
  • "filterUnread": "UNDEFINED_VALUE",
  • "itemsPerPage": 0,
  • "limitPagination": true,
  • "mailboxIds": [
    ],
  • "page": 0,
  • "query": "string",
  • "sortFromEmail": "UNDEFINED_SORT_ORDER",
  • "sortReceivedAt": "UNDEFINED_SORT_ORDER"
}

Response samples

Content type
application/json
{
  • "mails": [
    ],
  • "totalCount": 0,
  • "totalPageCount": 0
}

List mails by IDs

Returns the mails matching the given mail IDs.

Request Body schema: application/json
required
mailIds
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "mailIds": [
    ]
}

Response samples

Content type
application/json
{
  • "mails": [
    ]
}

List mails by reference IDs

Returns a paginated list of mails linked to the given reference IDs. Supports query text, folder filter, and optional mailbox IDs when filtering inbound/outbound. Response includes total mail and page counts.

Request Body schema: application/json
required
emailAddresses
Array of strings

Optional filter. At least one provided email address must be a participant (FROM, TO, CC or BCC)

filterFolder
required
string (v2FilterFolder)
Default: "FILTER_FOLDER_ALL"
Enum: "FILTER_FOLDER_ALL" "FILTER_FOLDER_INBOUND" "FILTER_FOLDER_OUTBOUND" "FILTER_FOLDER_ARCHIVED" "FILTER_FOLDER_TRASH" "FILTER_FOLDER_SPAM"
itemsPerPage
required
integer <int32>
mailboxIds
Array of strings

Optional filter that only needs to be set if filter folder is inbound/outbound

page
required
integer <int32>
query
required
string
referenceIds
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "emailAddresses": [
    ],
  • "filterFolder": "FILTER_FOLDER_ALL",
  • "itemsPerPage": 0,
  • "mailboxIds": [
    ],
  • "page": 0,
  • "query": "string",
  • "referenceIds": [
    ]
}

Response samples

Content type
application/json
{
  • "mails": [
    ],
  • "totalMailsCount": 0,
  • "totalPageCount": 0
}

Mark mails as not spam

Removes the spam flag from the mails identified by the given IDs.

Request Body schema: application/json
required
ids
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{ }

Mark mails as spam

Marks the mails identified by the given IDs as spam.

Request Body schema: application/json
required
ids
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{ }

Mark mails as read

Marks the given mails as read for the specified account.

Request Body schema: application/json
required
accountId
required
string <int64>
ids
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "accountId": "string",
  • "ids": [
    ]
}

Response samples

Content type
application/json
{ }

Mark mails as unread

Marks the given mails as unread for the specified account.

Request Body schema: application/json
required
accountId
required
string <int64>
ids
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "accountId": "string",
  • "ids": [
    ]
}

Response samples

Content type
application/json
{ }

Move mails to trash

Moves the mails identified by the given IDs to trash.

Request Body schema: application/json
required
ids
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{ }

Remove confidential emails

Removes the given email addresses from the confidential email list of the account.

Request Body schema: application/json
required
accountId
required
string <int64>
emails
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "accountId": "string",
  • "emails": [
    ]
}

Response samples

Content type
application/json
{ }

Unarchive mails

Restores the given mails from the archive.

Request Body schema: application/json
required
ids
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{ }

Restore mails from trash

Restores the mails identified by the given IDs from trash.

Request Body schema: application/json
required
ids
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{ }

Save a mail draft

Creates or updates a mail draft for the given mailbox. Optional id updates an existing draft; otherwise a new draft is created. Accepts participants, subject, body, attachments, and optional reply/forward mail IDs. Returns the saved draft.

Request Body schema: application/json
required
attachmentMediaIds
required
Array of strings
required
Array of objects (mailv2Participant)
bodyHtml
required
string
bodyText
required
string
required
Array of objects (mailv2Participant)
forwardingMailId
required
string
id
string

Optional parameter to save new drafts and update existing ones

mailboxId
required
string
referenceIds
required
Array of strings
replyToMailId
required
string
subject
required
string
timestamp
required
string <int64> (UNIX timestamp in seconds when draft was saved the last time)
required
Array of objects (mailv2Participant)

Responses

Request samples

Content type
application/json
{
  • "attachmentMediaIds": [
    ],
  • "bcc": [
    ],
  • "bodyHtml": "string",
  • "bodyText": "string",
  • "cc": [
    ],
  • "forwardingMailId": "string",
  • "id": "string",
  • "mailboxId": "string",
  • "referenceIds": [
    ],
  • "replyToMailId": "string",
  • "subject": "string",
  • "timestamp": "string",
  • "to": [
    ]
}

Response samples

Content type
application/json
{
  • "draft": {
    }
}

Send a mail

Sends a mail for the given owner with from/to/cc/bcc participants, subject, body, and optional attachments. Supports reply threading via replyToMailId, scheduled send via sendAt, and a confidential flag. Returns the sent mail.

Request Body schema: application/json
required
attachmentMediaIds
required
Array of strings
required
Array of objects (mailv2Participant)
bodyHtml
required
string
bodyText
required
string
required
Array of objects (mailv2Participant)
confidential
required
boolean
required
object (mailv2Participant)
mailType
string (v2MailType)
Default: "MAIL_TYPE_NORMAL"
Enum: "MAIL_TYPE_NORMAL" "MAIL_TYPE_IMIP" "MAIL_TYPE_TICKET_NOTIFICATION"
ownerId
required
string <int64>
referenceIds
required
Array of strings
replyToMailId
string

Optional: If set to id of mail the user replies to -> support for threaded mails

sendAt
string <int64>

Optional: for scheduled mails

subject
required
string
required
Array of objects (mailv2Participant)

Responses

Request samples

Content type
application/json
{
  • "attachmentMediaIds": [
    ],
  • "bcc": [
    ],
  • "bodyHtml": "string",
  • "bodyText": "string",
  • "cc": [
    ],
  • "confidential": true,
  • "from": {
    },
  • "mailType": "MAIL_TYPE_NORMAL",
  • "ownerId": "string",
  • "referenceIds": [
    ],
  • "replyToMailId": "string",
  • "sendAt": "string",
  • "subject": "string",
  • "to": [
    ]
}

Response samples

Content type
application/json
{
  • "mail": {
    }
}

Set automatic reply on mailboxes

Sets the automatic reply configuration (enabled flag, date/time window, subject and body) on the given mailbox IDs. Returns the updated mailboxes.

Request Body schema: application/json
required
required
object (v2AutomaticReply)
ids
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "automaticReply": {
    },
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "mailboxes": [
    ]
}

Set mails confidential flag

Sets the confidential flag on the mails identified by the given IDs.

Request Body schema: application/json
required
confidential
required
boolean
ids
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "confidential": true,
  • "ids": [
    ]
}

Response samples

Content type
application/json
{ }

Set mailboxes confidential flag

Sets the confidential flag on the given mailbox IDs. Returns the updated mailboxes.

Request Body schema: application/json
required
confidential
required
boolean
mailboxIds
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "confidential": true,
  • "mailboxIds": [
    ]
}

Response samples

Content type
application/json
{
  • "mailboxes": [
    ]
}

Set reference IDs on mails

Sets the reference IDs on the mails identified by the given IDs.

path Parameters
ids
required
Array of strings non-empty
Request Body schema: application/json
required
referenceIds
Array of strings

Responses

Request samples

Content type
application/json
{
  • "referenceIds": [
    ]
}

Response samples

Content type
application/json
{ }

Validate a mail domain

Validates the mail domain identified by the given ID and returns whether it is valid.

path Parameters
id
required
string
Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "isValid": true
}

SignatureService

List signatures by account ID

Returns all signatures belonging to the given account.

query Parameters
accountId
string <int64>

Responses

Response samples

Content type
application/json
{
  • "signatures": [
    ]
}

Render a signature by ID

Renders the signature identified by ID with placeholders replaced for the given user. Returns the rendered signature text.

path Parameters
id
required
string
userId
required
string

Responses

Response samples

Content type
application/json
{
  • "signature": "string"
}

Create or update a signature

Creates a new signature or updates an existing one when id is provided. Accepts account ID, name, and signature text. Returns the saved signature.

Request Body schema: application/json
required
accountId
required
string <int64>
id
required
string

OPTIONAL. If not provided a new signature is created

name
required
string
signature
required
string

Responses

Request samples

Content type
application/json
{
  • "accountId": "string",
  • "id": "string",
  • "name": "string",
  • "signature": "string"
}

Response samples

Content type
application/json
{
  • "signature": {
    }
}

Get account signature

Returns the signature for the given account. This is the legacy single-signature-per-account API.

path Parameters
accountId
required
string <int64>

Responses

Response samples

Content type
application/json
{
  • "signature": {
    }
}

Render account signature

Renders the account signature with placeholders replaced for the given user. Returns the rendered signature text.

path Parameters
accountId
required
string <int64>
userId
required
string

Responses

Response samples

Content type
application/json
{
  • "signature": "string"
}

Set account signature

Sets the signature text for the given account. This is the legacy single-signature-per-account API.

path Parameters
accountId
required
string <int64>
Request Body schema: application/json
required
signature
string

Responses

Request samples

Content type
application/json
{
  • "signature": "string"
}

Response samples

Content type
application/json
{ }

Delete a signature

Deletes the signature identified by the given ID.

path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{ }

TemplateService

Bulk render free-form template text

Renders the given text and optional title for multiple entries, each with contact, object, property, and building IDs. Returns one rendered text/title result per contact.

Request Body schema: application/json
required
required
Array of objects (v2BulkRenderTextEntry)
text
required
string
title
required
string

Responses

Request samples

Content type
application/json
{
  • "entries": [
    ],
  • "text": "string",
  • "title": "string"
}

Response samples

Content type
application/json
{
  • "entries": [
    ]
}

Create a message template

Creates a new message template for the given owner. Accepts type (email, letter, ticket, or deep sign), name, subject, message body, optional attachment media IDs, and language. Returns the created template.

Request Body schema: application/json
required
attachmentMediaIds
required
Array of strings
language
required
string
message
required
string
name
required
string
ownerId
required
string <int64>
subject
required
string
type
required
string (v2TemplateType)
Default: "TEMPLATE_TYPE_EMAIL"
Enum: "TEMPLATE_TYPE_EMAIL" "TEMPLATE_TYPE_LETTER" "TEMPLATE_TYPE_TICKET" "TEMPLATE_TYPE_DEEP_SIGN"

Responses

Request samples

Content type
application/json
{
  • "attachmentMediaIds": [
    ],
  • "language": "string",
  • "message": "string",
  • "name": "string",
  • "ownerId": "string",
  • "subject": "string",
  • "type": "TEMPLATE_TYPE_EMAIL"
}

Response samples

Content type
application/json
{
  • "template": {
    }
}

List message templates for an owner

Returns all message templates belonging to the given owner.

query Parameters
ownerId
string <int64>

Responses

Response samples

Content type
application/json
{
  • "templates": [
    ]
}

Render free-form template text

Renders the given text and optional title using contact and object IDs for placeholder substitution. Returns the rendered text and title.

Request Body schema: application/json
required
contactId
required
string
objectId
required
string
text
required
string
title
required
string

Responses

Request samples

Content type
application/json
{
  • "contactId": "string",
  • "objectId": "string",
  • "text": "string",
  • "title": "string"
}

Response samples

Content type
application/json
{
  • "text": "string",
  • "title": "string"
}

Delete message templates

Deletes the message templates identified by the given IDs.

path Parameters
ids
required
Array of strings non-empty

Responses

Response samples

Content type
application/json
{ }

Render a message template

Renders the template identified by ID using optional contact, object, property, and building IDs for placeholder substitution. Returns subject, rendered text, and attachment media IDs.

path Parameters
id
required
string
Request Body schema: application/json
required
buildingId
string
contactId
string
objectId
string
propertyId
string

Responses

Request samples

Content type
application/json
{
  • "buildingId": "string",
  • "contactId": "string",
  • "objectId": "string",
  • "propertyId": "string"
}

Response samples

Content type
application/json
{
  • "attachmentMediaIds": [
    ],
  • "subject": "string",
  • "text": "string"
}

Update a message template

Updates an existing message template by ID, including name, subject, message body, attachment media IDs, and language.

path Parameters
id
required
string
Request Body schema: application/json
required
attachmentMediaIds
Array of strings
language
string
message
string
name
string
subject
string

Responses

Request samples

Content type
application/json
{
  • "attachmentMediaIds": [
    ],
  • "language": "string",
  • "message": "string",
  • "name": "string",
  • "subject": "string"
}

Response samples

Content type
application/json
{ }