Manage domains and mailboxes
Learn how to manage and customize domains and mailboxes to collect payables in a single place and automatically upload them into the Monite platform.
Note
The email size limit is 25 MB for each inbound email message (including attachments).
Manage domains
By default, automatically created mailboxes belong to the Monite domain (the web address that comes after @
in an email address), but the partners can set up their own email domain for better convenience.
List all domains
To list all the domains registered in the system, call GET /mailbox_domains
:
curl -X GET 'https://api.sandbox.monite.com/v1/mailbox_domains' \
-H 'X-Monite-Version: 2023-03-14' \
-H 'Authorization: Bearer YOUR_PARTNER_TOKEN'
The successful response contains information about the domains registered in the system:
{
"data": [
{
"id": "63c40787-97da-4332-9415-9638cb0ea8bd",
"domain": "domainExample.com",
"status": "waiting_to_be_verified",
"provider": "mailgun",
"dns_records": {
"sending_dns_records": [
{
"name": "monite.com.br",
"valid": "unknown",
"value": "v=spf1 include:mailgun.org ~all",
"cached": [],
"record_type": "TXT"
}
],
"receiving_dns_records": [
{
"valid": "unknown",
"value": "mxa.eu.mailgun.org",
"cached": [],
"priority": "10",
"record_type": "MX"
}
]
}
}
]
}
Create a domain
To create a new domain, call POST /mailbox_domains
:
curl -X POST 'https://api.sandbox.monite.com/v1/mailbox_domains' \
-H 'X-Monite-Version: 2023-03-14' \
-H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"domain": "domainExample.com",
"provider": "mailgun"
}'
The successful response contains information about the created domain:
{
"id": "8a91507e-63b4-4eb6-9354-dc5ec4251815",
"domain": "domainExample.com",
"status": "waiting_to_be_verified",
"provider": "mailgun",
"dns_records": {
"sending_dns_records": [
{
"cached": [],
"name": "domainExample.com",
"record_type": "TXT",
"valid": "unknown",
"value": "v=spf1 include:mailgun.org ~all"
}
],
"receiving_dns_records": [
{
"cached": [],
"priority": "10",
"record_type": "MX",
"valid": "unknown",
"value": "mxa.eu.mailgun.org"
}
]
}
}
Set up a domain's DNS records
After receiving the required DNS records in the previous step, you have to enter these settings in the control panel of your domain provider.
Verify a domain
The mail service provider used by Monite automatically verifies the associated domains on a regular basis (one or more times a day).
However, you can also trigger domain verification manually by calling POST /mailbox_domains/{domain_id}/verify
:
curl -X POST 'https://api.sandbox.monite.com/v1/mailbox_domains/63c40787...b0ea8bd/verify' \
-H 'X-Monite-Version: 2023-03-14' \
-H 'Authorization: Bearer YOUR_PARTNER_TOKEN'
In case of successful verification, the response will return status
set to verified
:
{
"id": "8a91507e-63b4-4eb6-9354-dc5ec4251815",
"domain": "domainExample.com",
"status": "verified",
"provider": "mailgun"
}
If the verification fails, the response will contain status
set to waiting_to_be_verified
. To resolve this issue, ensure the DNS records required for this mailbox domain are matching the records you provided in a control panel of your domain provider in the previous step.
Update a domain
It is not possible to update an existing domain. If some data has to be changed, you need to delete the domain and then create it again. To delete a domain, call DELETE /mailbox_domains/{domain_id}
:
curl -X DELETE 'https://api.sandbox.monite.com/v1/mailbox_domains/63c40787...b0ea8bd' \
-H 'X-Monite-Version: 2023-03-14' \
-H 'Authorization: Bearer YOUR_PARTNER_TOKEN'
The successful response indicates that the domain was deleted successfully.
Manage mailboxes
After you have added your custom domain to Monite, you can associate specific mailboxes within this domain with specific entities.
Associate a mailbox with an entity
To associate a mailbox with an entity, call POST /mailboxes
as shown below. Replace mailbox_name
with the part of the email address before the @
, and mailbox_domain_id
with the ID of the domain that you previously added:
curl -X POST 'https://api.sandbox.monite.com/v1/mailboxes' \
-H 'X-Monite-Version: 2023-03-14' \
-H 'X-Monite-Entity-Id: ENTITY_ID' \
-H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"related_object_type": "payable",
"mailbox_name": "mailboxExample"
"mailbox_domain_id": "8a91507e-63b4-4eb6-9354-dc5ec4251815"
}
The response contains the full email address (mailbox_full_address
) associated with this entity:
{
"id": "e8c884f8-bed3-4d92-afc9-3538c5079014",
"status": "active",
"related_object_type": "payable",
"mailbox_name": "mailboxExample",
"mailbox_full_address": "[email protected]",
"belongs_to_mailbox_domain_id": "8a91507e-63b4-4eb6-9354-dc5ec4251815"
}
Now the entity can receive invoices to this mailbox. Any invoices sent as email attachments to this mailbox will be registered as new payables for that entity and trigger the related approval policies.
List all mailboxes
To retrieve all the mailboxes used to process incoming invoices of a specific entity, call GET /mailboxes
:
curl -X GET 'https://api.sandbox.monite.com/v1/mailboxes' \
-H 'X-Monite-Version: 2023-03-14' \
-H 'X-Monite-Entity-Id: ENTITY_ID' \
-H 'Authorization: Bearer YOUR_PARTNER_TOKEN'
The successful response contains a list of all the mailboxes associated with this entity:
[
{
"id": "e8c884f8-bed3-4d92-afc9-3538c5079014",
"status": "active",
"related_object_type": "payable",
"mailbox_name": "1102737648192968373_payables",
"mailbox_full_address": "[email protected]",
"belongs_to_mailbox_domain_id": null
}
]
Update a mailbox
It is not possible to update an existing mailbox. If some data has to be changed, you need to delete the mailbox and then create it again. To delete a mailbox, call DELETE /mailboxes/{mailbox_id}
:
curl -X DELETE 'https://api.sandbox.monite.com/v1/mailboxes/e8c884f8-bed3-4d92-afc9-3538c5079014' \
-H 'X-Monite-Version: 2023-03-14' \
-H 'X-Monite-Entity-Id: ENTITY_ID' \
-H 'Authorization: Bearer YOUR_PARTNER_TOKEN'
The successful response indicates that the mailbox was deleted successfully.
Updated 17 days ago