EMS documentation contains in-depth examples how to assemble and send a message. See the documentation of the sandbox instance, for example — https://api-ems-eu10.erply.com/documentation/index.html#/ — and expand the “Messages” section at the beginning of the page.
However, EMS does not let you arbitrarily set a sender address. This document explains the best practice for populating the sender field.
Use case
This document assumes that you are a developer implementing emailing functionality in an Erply application or a plugin — and the feature will be used by Erply users, to send messages to their clients.
If you want to send a sales document Actual Reports custom printout, take a look at POST /v1/sales/documents/by-email in Sales Document API.
For other use cases, see below.
Recommendations
In EMS POST /api/v2/message, the “from” address must always correspond to one of the account’s mailboxes. It cannot be an arbitrary address.
To populate the “from” address, you should therefore query EMS for available mailboxes and automatically pick one of these. In back office, we established that we will pick the primary mailbox with the highest ID. The corresponding query to retrieve it is:
GET /api/v2/mailbox?mailboxIsPrimary=true&sort=-idThe real sender address can be attached to the message as a “reply-to” contact.
However, to make things a bit more user-friendly, both the “from” and “reply-to” contacts can still have a name, too, and it can be set to the real sender’s name (for example, the company name).
This is how it should look to the end users: https://wiki.erply.com/article/595-emailing-from-erply
ca.erply.io domain name for Canada
By default, all accounts in the North & South America region use “us.erply.io” domain name for mailboxes and outgoing emails.
For a Canadian account, it is possible to replace it with “ca.erply.io”.
In order to switch an account over to ca.erply.io domain, add a new parameter from Configuration Admin -> Parameters:
name: ems_email_domain
value: ca.erply.ioThis will have the following effect:
- Whatever old alias (part before the @) was registered for the account, will still remain valid for Canada addresses as well
- It will be possible to send e-mails using the Canada domain, but not possible to send using US domain any longer
- All old messages will remain as they are - showing the old US address. New messages will have the Canada address
- When a list of mailboxes is requested from EMS, the primary mailboxes will use the Canada domain. Any other old mailboxes will remain as they were - with a US address. The previously “primary” US addresses are no longer flagged as “primary” but they are still listed as there are probably existing messages that use these addresses