Domains and mailboxes

Learn how to manage and customize domains and mailboxes to collect payables in a single place and automatically upload them to the Monite platform.

The email size limit is 25 MB for each inbound email message (including attachments).

Overview

Monite automatically creates mailboxes for partners. These mailboxes are on Monite’s domain—monite.com; thus, the email address on all Monite emails is always noreply@monite.com by default. However, partners can opt to set up their email domain for better convenience.

Once a domain is created and verified, for example, mycompany.com, the emails Monite sends will also have noreply@mycompany.com in the from header by default. This custom domain will also be displayed in the email’s mailed-by and signed-by MIME headers.

You can customize the email sender name and username by updating your Monite partner settings. For more information, see Update partner settings.

If the entity users already have their own custom emails shared with their vendors to collect their payables, the entity users can automatically forward their received emails to a mailbox of the partner, where the payables will be collected.

Roles and permissions

The following endpoints must be accessed using a partner access token:

  • /mailbox_domains*
  • GET /mailboxes/search

The following endpoints can be accessed using both partner tokens and entity user access tokens. Entity users need a role with the mailbox permissions to access these endpoints.

  • GET /mailboxes
  • POST /mailboxes
  • DELETE /mailboxes/{mailbox_id}

Manage domains

List all domains

To list all the domains registered in the system, send a GET request to the /mailbox_domains endpoint:

1curl -X GET 'https://api.sandbox.monite.com/v1/mailbox_domains' \
2     -H 'X-Monite-Version: 2023-09-01' \
3     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN'

The successful response contains information about the domains registered in the system:

1{
2  "data": [
3    {
4      "id": "63c40787-97da-4332-9415-9638cb0ea8bd",
5      "domain": "domainexample.com",
6      "status": "waiting_to_be_verified",
7      "dedicated_ip": "123.456.789.101",
8      "last_updated_at": "2024-01-15T09:30:00Z",
9      "dns_records": {
10        "sending_dns_records": [
11          {
12            "is_active": true,
13            "name": "name",
14            "record_purpose": "DKIM",
15            "valid": "unknown",
16            "value": "v=spf1 include:mailgun.org ~all",
17            "record_type": "TXT"
18          }
19        ],
20        "receiving_dns_records": [
21          {
22            "is_active": true,
23            "name": "name",
24            "record_purpose": "DKIM",
25            "valid": "unknown",
26            "value": "mxa.eu.mailgun.org",
27            "record_type": "TXT"
28          }
29        ]
30      }
31    }
32  ]
33}

Create a domain

To create a new domain, send a POST request to the /mailbox_domains endpoint:

1curl -X POST 'https://api.sandbox.monite.com/v1/mailbox_domains' \
2     -H 'X-Monite-Version: 2023-09-01' \
3     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
4     -H 'Content-Type: application/json' \
5     -d '{
6       "domain": "domainexample.com"
7     }'

Different domains per environment

You must use different domain names in the Sandbox and Production environments. For example, mail.sandbox.mycompany.com in Sandbox and mail.mycompany.com in Production.

You cannot create a Production domain with the same domain name as in Sandbox, and vice versa.

The successful response contains information about the created domain:

1{
2  "id": "8a91507e-63b4-4eb6-9354-dc5ec4251815",
3  "domain": "domainexample.com",
4  "status": "waiting_to_be_verified",
5  "name": "name",
6  "record_purpose": "DKIM",
7  "dedicated_ip": "dedicated_ip",
8  "last_updated_at": "2024-01-15T09:30:00Z",
9  "dns_records": {
10    "sending_dns_records": [
11      {
12        "is_active": true,
13        "valid": "unknown",
14        "value": "v=spf1 include:mailgun.org ~all",
15        "record_type": "TXT"
16      }
17    ],
18    "receiving_dns_records": [
19      {
20        "is_active": true,
21        "valid": "unknown",
22        "value": "mxa.eu.mailgun.org",
23        "record_type": "TXT"
24      }
25    ]
26  }
27}

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:

1curl -X POST 'https://api.sandbox.monite.com/v1/mailbox_domains/63c40787...b0ea8bd/verify' \
2     -H 'X-Monite-Version: 2023-09-01' \
3     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' 
4     -d ''

In case of successful verification, the response will return status set to verified:

1{
2  "id": "8a91507e-63b4-4eb6-9354-dc5ec4251815",
3  "domain": "domainexample.com",
4  "status": "verified"
5}

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 match the records you provided in the 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}:

1curl -X DELETE 'https://api.sandbox.monite.com/v1/mailbox_domains/63c40787...b0ea8bd' \
2     -H 'X-Monite-Version: 2023-09-01' \
3     -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.

These entity mailboxes are not created by default and, thus, need to be created by the partners. The domain should be verified.

The mailbox name can contain only lowercase letters (from a to z), digits (from 0 to 9), and the characters ., _, +, and -.

Associate a mailbox with an entity

To associate a mailbox with an entity, call POST /mailboxes as shown below. The mailbox_name field represents the part of the email address before the @ and the mailbox_domain_id field represents the ID of the domain that you previously added:

1curl -X POST 'https://api.sandbox.monite.com/v1/mailboxes' \
2     -H 'X-Monite-Version: 2023-09-01' \
3     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4     -H 'Authorization: Bearer ACCESS_TOKEN' \
5     -H 'Content-Type: application/json' \
6     -d '{
7       "related_object_type": "payable",
8       "mailbox_name": "mailboxexample"
9       "mailbox_domain_id": "8a91507e-63b4-4eb6-9354-dc5ec4251815"
10     }

The response contains the full email address (mailbox_full_address) associated with this entity:

1{
2  "id": "e8c884f8-bed3-4d92-afc9-3538c5079014",
3  "status": "active",
4  "related_object_type": "payable",
5  "mailbox_name": "mailboxexample",
6  "mailbox_full_address": "mailboxexample@domainexample.com",
7  "mailbox_domain_id": "8a91507e-63b4-4eb6-9354-dc5ec4251815"
8}

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 payables of the connected entity, call GET /mailboxes:

1curl -X GET 'https://api.sandbox.monite.com/v1/mailboxes' \
2     -H 'X-Monite-Version: 2023-09-01' \
3     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4     -H 'Authorization: Bearer ACCESS_TOKEN'

The successful response contains a list of all the mailboxes associated with this entity:

1{
2  data: [
3    {
4      "id": "e8c884f8-bed3-4d92-afc9-3538c5079014",
5      "status": "active",
6      "related_object_type": "payable",
7      "mailbox_name": "1102737648192968373_payables",
8      "mailbox_full_address": "1102737648192968373_payables@mg.sandbox.monite.com",
9      "mailbox_domain_id": null
10    }
11  ]
12}

Partners can list all the mailboxes of a given list of entity IDs by calling POST /mailboxes/search.

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}:

1curl -X DELETE 'https://api.sandbox.monite.com/v1/mailboxes/e8c884f8-bed3-4d92-afc9-3538c5079014' \
2     -H 'X-Monite-Version: 2023-09-01' \
3     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4     -H 'Authorization: Bearer ACCESS_TOKEN'

The successful response indicates that the mailbox was deleted successfully.