Mailbox API – Mails Create and Send

The Mailbox API is available starting with Axigen X4 (10.4).

Create
Replace Draft
Send UPDATED
Temporary Attachments
- Create
- Get
- Delete
- Store in Queue

Create

This endpoint allows you to create a new draft email or insert an email into an existing folder.

If folderId is specified, the email will be appended to the specified folder, otherwise it will be created as a draft, in the Drafts folder.

Request body (JSON)

Name	Type	Required	Values	Description
`folderId`	`String`			The default value is the ID of the “Drafts” folder
`from`	`String`			The desired value of the `from` header
`to`	`String`			The desired value of the `to` header
`cc`	`String`			The desired value of the `cc` header
`bcc`	`String`			The desired value of the `bcc` header
`replyTo`	`String`			The desired value of the `Reply-To` header
`refwType`	`String`		"re", "fw"	Whether the mail is a reply or a forward. The mail cannot be both a reply and a forward (“refw” is an invalid value)
`refwMailId`	`String`	Required if `refw` is set		This field is dependent on `refwType`: `refwType` missing: `refwMailId` should not be sent `refwType` set to "re": `refwMailId` required, the ID of the mail being replied to. This ID is used to automatically generate the `References` and `In-Reply-To` headers for replies. `refwType` set to "fw": `refwMailId` required, the ID of the mail being forwarded
`subject`	`String`			The desired value of the `Subject` header
`isUnread`	`Boolean`			The unread / read value
`isFlagged`	`Boolean`			The flagged / not flagged value
`importance`	`String`			"normal", "low", "high" The desired importance. If missing, the importance will default to "normal".
`bodyText`	`String`			The UTF-8 text body, if existing
`bodyHtml`	`String`			The UTF-8 HTML body, if existing
`temporaryAttachments`	`Array`		JSON object list in the following format:	The attachments in the attachments queue.

Response

If successful, the response will contain an instance of mail.

Replace Draft

This endpoint allows you to replace an existing draft email.

URL parameters

Name	Type	Required	Values	Description
`mailId`	`String`	*		The draft mail ID

Request body (JSON)

Name	Type	Required	Values	Description
`from`	`String`			The desired value of the `from` header
`to`	`String`			The desired value of the `to` header
`cc`	`String`			The desired value of the `cc` header
`bcc`	`String`			The desired value of the `bcc` header
`replyTo`	`String`			The desired value of the `Reply-To` header
`refwType`	`String`		"re", "fw"	Whether the mail is a reply or a forward. The mail cannot be both a reply and a forward (“refw” is an invalid value)
`refwMailId`	`String`	Required if `refw` is set		This field is dependent on `refw`: `refwType` missing: `refwMailId` should not be sent `refwType` set to "re": `refwMailId` required, the ID of the mail being replied to. This ID is used to automatically generate the `References` and `In-Reply-To` headers for replies. `refwType` set to "fw": `refwMailId` required, the ID of the mail being forwarded
`subject`	`String`			The desired value of the `Subject` header
`isUnread`	`Boolean`			The unread / read value
`isFlagged`	`Boolean`			The flagged / not flagged value
`importance`	`String`			"normal", "low", "high" The desired importance. If missing, the importance will default to "normal".
`bodyText`	`String`			The UTF-8 text body, if existing
`bodyHtml`	`String`			The UTF-8 HTML body, if existing
`temporaryAttachments`	`Array`		JSON object list in the following format:	The attachments in the attachments queue.

Response

If successful, the response will contain an instance of mail.

Send UPDATED

Send Mail

This endpoint allows you to send an email which is not yet saved to Drafts.

It will also save a copy to Sent according to the user preference.

Request body (JSON)

Name	Type	Required	Values	Description
`from`	`String`			The desired value of the `from` header
`to`	`String`			The desired value of the `to` header
`cc`	`String`			The desired value of the `cc` header
`bcc`	`String`			The desired value of the `bcc` header
`replyTo`	`String`			The desired value of the `Reply-To` header
`refwType`	`String`		"re", "fw"	Whether the mail is a reply or a forward. The mail cannot be both a reply and a forward (“refw” is an invalid value)
`refwMailId`	`String`	Required if `refw` is set		This field is dependent on `refwType`: `refwType` missing: `refwMailId` should not be sent `refwType` set to "re": `refwMailId` required, the ID of the mail being replied to. This ID is used to automatically generate the `References` and `In-Reply-To` headers for replies. `refwType` set to "fw": `refwMailId` required, the ID of the mail being forwarded
`subject`	`String`			The desired value of the `Subject` header
`importance`	`String`			"normal", "low", "high" The desired importance. If missing, the importance will default to "normal".
`requestReadReceipt`	`Boolean`			Whether to request a read receipt
`requestDeliveryReceipt`	`Boolean`			Whether to request a delivery receipt
`bodyText`	`String`			The UTF-8 text body, if existing
`bodyHtml`	`String`			The UTF-8 HTML body, if existing
`temporaryAttachments`	`Array`		JSON object list in the following format:	The attachments in the attachments queue.

Response

If successful, the response will be empty.

Starting with Axigen X5 (10.5), as part of the planned support for the Undo Send functionality, if successful, the server response will be as documented below.

Send Draft

This endpoint allows you to send an existing draft email.

If this is preceded by opening the draft for editing, on send you should first save it to drafts and then call this endpoint with the draft mail ID.

This endpoint will also delete the draft upon sending and will save a copy to Sent according to the user preference.

URL parameters

Name	Type	Required	Values	Description
`mailId`	`String`	*		The draft mail ID

Response

If successful, the response will be empty.

Starting with Axigen X5 (10.5), as part of the planned support for the Undo Send functionality, if successful, the server response will be as documented below.

Undo Send

This endpoint allows you to stop the server from delivering a mail in the processing queue. Can be successfully used after a maximum of 10 seconds after the mail was sent.

If the mail is a reply/forward, after undo, the source mail will lose their respective Replied/Answered flag (This happens even when the source mail had the flag set before the reply was sent!).

If mailId is specified, the corresponding email will be moved to the Drafts folder. It is intended to be used with the response from the Send and Send Draft endpoints.

If mailId is not specified or something goes wrong when moving, a draft will be built based on the mail removed from the processing queue. In this case, the original BCC information will not be available anymore.

Request body (JSON)

Name	Type	Required	Values	Description
`processingId`	`Number`	*		Id of the mail in the processing queue for which to undo send
`mailId`	`String`			Id of the mail to move to drafts

Response

If the draft creation fails, the endpoint execution will be successful but the mailId in the response will not be returned.

Scheduled Send

This endpoint allows you to schedule delivery of an email which is not yet saved to Drafts, at a desired timestamp in the future

It will also save a copy to the Scheduled folder to facilitate user interaction

The user can choose to delete the mail, in which case, it will also be unscheduled

Upon first delivery attempt, the mail is automatically moved from the user’s Scheduled folder to the Sent folder, or permanently deleted (according to the user’s saveToSent configuration)

Request body (JSON)

Name	Type	Required	Values	Description
`deliveryTime`	`Number`	*	unix timestamp as unsigned 64 bit int (seconds) e.g. we use `"deliveryTime" : 1680171858` for delivering at Thu Mar 30 2023 12:24:18 GMT+0200 (Central European Summer Time)	Timestamp when the mail should be delivered (up to 1 year into the future)
`from`	`String`			The desired value of the `from` header
`to`	`String`			The desired value of the `to` header
`cc`	`String`			The desired value of the `cc` header
`bcc`	`String`			The desired value of the `bcc` header
`replyTo`	`String`			The desired value of the `Reply-To` header
`refwType`	`String`		"re", "fw"	Whether the mail is a reply or a forward. The mail cannot be both a reply and a forward (“refw” is an invalid value)
`refwMailId`	`String`	Required if `refw` is set		This field is dependent on `refwType`: `refwType` missing: `refwMailId` should not be sent `refwType` set to "re": `refwMailId` required, the ID of the mail being replied to. This ID is used to automatically generate the `References` and `In-Reply-To` headers for replies. `refwType` set to "fw": `refwMailId` required, the ID of the mail being forwarded
`subject`	`String`			The desired value of the `Subject` header
`importance`	`String`			"normal", "low", "high" The desired importance. If missing, the importance will default to "normal".
`requestReadReceipt`	`Boolean`			Whether to request a read receipt
`requestDeliveryReceipt`	`Boolean`			Whether to request a delivery receipt
`bodyText`	`String`			The UTF-8 text body, if existing
`bodyHtml`	`String`			The UTF-8 HTML body, if existing
`temporaryAttachments`	`Array`		JSON object list in the following format:	The attachments in the attachments queue.

Response

If successful, the response will contain the mail id of the mail saved to the Scheduled folder

Scheduled Send Draft

This endpoint allows you to schedule delivery of an existing draft mail, at a desired timestamp in the future

If this is preceded by opening the draft for editing, on send you should first save it to drafts and then call this endpoint with the draft mail ID

It will move the draft to the Scheduled folder to facilitate user interaction

The user can choose to delete the mail, in which case, it will also be unscheduled

Upon first delivery attempt, the mail is automatically moved from the user’s Scheduled folder to the Sent folder, or permanently deleted (according to the user’s saveToSent configuration)

URL parameters

Name	Type	Required	Values	Description
`mailId`	`String`	*		The draft mail ID

Request body (JSON)

Name

Type

Required

Values

Description

deliveryTime

Number

unix timestamp as unsigned 64 bit int (seconds)

e.g. we use "deliveryTime" : 1680171858 for delivering at

Thu Mar 30 2023 12:24:18 GMT+0200 (Central European Summer Time)

Timestamp when the mail should be delivered (up to 1 year into the future)

Response

If successful, the response will contain the mail id of the mail saved to the Scheduled folder

Scheduled Cancel

This endpoint allows you to cancel delivery of a previously scheduled mail

It will move the targeted mail from the Scheduled folder to the Drafts folder

URL parameters

Name	Type	Required	Values	Description
`mailId`	`String`	*		The scheduled mail ID

Response

If successful, the response will contain the mail id of the mail saved to the Drafts folder

Temporary Attachments

Axigen uses an attachments queue for attachment uploads.

1. To attach a file to a message as a regular attachment:

a. Use the “Create” endpoint to upload the file
b. Pass the temporaryAttachments array to the “Send” or “Save” endpoint.

2. To attach a file to a message as an inline attachment:

a. Use the “Create” endpoint to upload the file
b. Generate a unique contentId and refer it as a cid source for the corresponding inline image in your email body.
This will ensure that your mail body will contain a valid reference for each inline attachment.
c. Pass the temporaryAttachments array (including the contentId and the isInline property set to true) to the “Send” or “Save” endpoint.

3. When forwarding an email or opening a draft for editing:

a. Add the existing attachments to the internal queue by calling the “Store” endpoint
b. Update your email body and attachments list to point to the internal queue attachments instead of the original ones (both inline and regular attachments).

Create

Request body

Include the attachment as a multipart/form-data HTTP body part.

Response

Get

URL parameters

Name	Type	Required	Values	Description
`temporaryAttachmentId`	`String`	*		The temporary attachment ID

Response

The temporary attachment.

Delete

URL parameters

Name	Type	Required	Values	Description
`temporaryAttachmentId`	`String`	*		The temporary attachment ID

Response

If successful, the response will be empty.

Store in Queue

This endpoint allows you to store an email’s attachments in the internal queue.

Request body (JSON)

Name	Type	Required	Values	Description
`mailId`	`String`	*		The mail ID whose attachments you want to store.

Response

The IDs of the temporary attachments are not related to the original mail; they are internal queue unique identifiers.