> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tesouro.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 Tesouro platform.

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

## Overview

Tesouro automatically creates mailboxes for [partners](/finops/support/glossary#partner). These mailboxes are on Tesouro's domain—`tesouro.com`; thus, the email address on all Tesouro emails is always `noreply@tesouro.com` by default. However, partners can opt to set up their email domain for better convenience.

Once a domain is [created](#create-domain) and [verified](#verify-domain), for example, `mycompany.com`, the emails Tesouro 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](https://en.wikipedia.org/wiki/MIME) headers.

You can customize the email sender name and username by updating your Tesouro partner settings.

<Tip>
  If the [organization users](/finops/guides/organizations/users) already have their own custom emails shared
  with their vendors to collect their payables, the organization users can automatically forward
  their received emails to a mailbox of the partner, where the payables will be collected.
</Tip>

## Roles and permissions

The following endpoints must be accessed using a [partner access token](/finops/guides/authentication/client-credentials):

* `/mailbox-domains*`
* `GET /mailboxes/search`

The following endpoints can be accessed using both app tokens and [organization user access tokens](/finops/guides/organizations/users#get-organization-user-token). Organization users need a [role](/finops/guides/organizations/users#create-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`](/finops/reference/openapi/mailbox-domains/get-mailbox-domains) endpoint:

```sh lines theme={null}
curl -X GET 'https://api.sandbox.tesouro.com/v1/mailbox-domains' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

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

```json expandable lines theme={null}
{
  "data": [
    {
      "id": "63c40787-97da-4332-9415-9638cb0ea8bd",
      "domain": "domainexample.com",
      "status": "waiting_to_be_verified",
      "dedicated_ip": "123.456.789.101",
      "last_updated_at": "2024-01-15T09:30:00Z",
      "dns_records": {
        "sending_dns_records": [
          {
            "is_active": true,
            "name": "name",
            "record_purpose": "DKIM",
            "valid": "unknown",
            "value": "v=spf1 include:mailgun.org ~all",
            "record_type": "TXT"
          }
        ],
        "receiving_dns_records": [
          {
            "is_active": true,
            "name": "name",
            "record_purpose": "DKIM",
            "valid": "unknown",
            "value": "mxa.eu.mailgun.org",
            "record_type": "TXT"
          }
        ]
      }
    }
  ]
}
```

### Create a domain

To create a new domain, send a `POST` request to the [`/mailbox-domains`](/finops/reference/openapi/mailbox-domains/post-mailbox-domains) endpoint:

```sh lines theme={null}
curl -X POST 'https://api.sandbox.tesouro.com/v1/mailbox-domains' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "domain": "domainexample.com"
     }'
```

<Warning>
  **Different domains per environment**

  You must use different domain names in the Sandbox and Production [environments](/finops/api/concepts/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.
</Warning>

The successful response contains information about the created domain:

```json expandable lines theme={null}
{
  "id": "8a91507e-63b4-4eb6-9354-dc5ec4251815",
  "domain": "domainexample.com",
  "status": "waiting_to_be_verified",
  "name": "name",
  "record_purpose": "DKIM",
  "dedicated_ip": "dedicated_ip",
  "last_updated_at": "2024-01-15T09:30:00Z",
  "dns_records": {
    "sending_dns_records": [
      {
        "is_active": true,
        "valid": "unknown",
        "value": "v=spf1 include:mailgun.org ~all",
        "record_type": "TXT"
      }
    ],
    "receiving_dns_records": [
      {
        "is_active": true,
        "valid": "unknown",
        "value": "mxa.eu.mailgun.org",
        "record_type": "TXT"
      }
    ]
  }
}
```

### 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 Tesouro 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`](/finops/reference/openapi/mailbox-domains/post-mailbox-domains-id-verify):

```sh lines theme={null}
curl -X POST 'https://api.sandbox.tesouro.com/v1/mailbox-domains/63c40787...b0ea8bd/verify' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
     -d ''
```

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

```json lines theme={null}
{
  "id": "8a91507e-63b4-4eb6-9354-dc5ec4251815",
  "domain": "domainexample.com",
  "status": "verified"
}
```

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}`](/finops/reference/openapi/mailbox-domains/delete-mailbox-domains-id):

```sh lines theme={null}
curl -X DELETE 'https://api.sandbox.tesouro.com/v1/mailbox-domains/63c40787...b0ea8bd' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

The successful response indicates that the domain was deleted successfully.

## Manage mailboxes

After you have added your custom domain to Tesouro, you can associate specific mailboxes within this domain with specific organizations.

These organization mailboxes are not created by default and, thus, need to be created by the partners. The domain should be [verified](#verify-domain).

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

### Associate a mailbox with an organization

To associate a mailbox with an organization, call [`POST /mailboxes`](/finops/reference/openapi/mailboxes/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:

```sh lines theme={null}
curl -X POST 'https://api.sandbox.tesouro.com/v1/mailboxes' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_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 organization:

```json lines theme={null}
{
  "id": "e8c884f8-bed3-4d92-afc9-3538c5079014",
  "status": "active",
  "related_object_type": "payable",
  "mailbox_name": "mailboxexample",
  "mailbox_full_address": "mailboxexample@domainexample.com",
  "mailbox_domain_id": "8a91507e-63b4-4eb6-9354-dc5ec4251815"
}
```

Now the organization can receive invoices to this mailbox. Any invoices sent as email attachments to this mailbox will be registered as new [payables](/finops/guides/accounts-payable/payables/collect) for that organization and trigger the related [approval policies](/finops/guides/accounts-payable/approvals/policies/index). You can also set mailboxes for collecting [receipts](/finops/guides/expense-management/receipts).

### List all mailboxes

To retrieve all the mailboxes used to process payables of the connected organization, call [`GET /mailboxes`](/finops/reference/openapi/mailboxes/get-mailboxes):

```sh lines theme={null}
curl -X GET 'https://api.sandbox.tesouro.com/v1/mailboxes' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN'
```

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

```json lines theme={null}
{
  "data": [
    {
      "id": "e8c884f8-bed3-4d92-afc9-3538c5079014",
      "status": "active",
      "related_object_type": "payable",
      "mailbox_name": "1102737648192968373_payables",
      "mailbox_full_address": "1102737648192968373_payables@mg.sandbox.tesouro.com",
      "mailbox_domain_id": null
    }
  ]
}
```

<Info>
  Partners can list all the mailboxes of a given list of organization IDs by calling [`POST
      /mailboxes/search`](/finops/reference/openapi/mailboxes/post-mailboxes-search).
</Info>

### 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}`](/finops/reference/openapi/mailboxes/delete-mailboxes-id):

```sh lines theme={null}
curl -X DELETE 'https://api.sandbox.tesouro.com/v1/mailboxes/e8c884f8-bed3-4d92-afc9-3538c5079014' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN'
```

The successful response indicates that the mailbox was deleted successfully.