Customers

Group your organization's domains by customer, such as the clients you manage as an MSP. Customers let you filter the domain list, send a scheduled report per customer, and see the estimated cost per customer on the billing page. In the dashboard, they live under Domains → Manage customers; see Customers and Tags.

Like domains, customers belong to the whole organization: any token can list and read them, and a token that isn't read-only can also create, change and delete them, and assign domains to them.

The Customer Object

Field	Type	Description
`id`	uuid	Customer ID
`name`	string	Unique in your organization, ignoring case
`description`	string or null	Your own notes about the customer
`color`	string or null	The hex color the dashboard shows the customer in, such as `#0080dd`
`contactEmail`	string or null	The customer's point of contact. The customer's scheduled reports go to this address as well as to the report's own recipients
`domainCount`	integer	How many domains are assigned to the customer
`createdAt`	string	When the customer was created
`updatedAt`	string	When the customer last changed

List Customers

Returns a paginated list of your customers, sorted by name.

GET /api/v1/customers

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	20	Items per page, 1 to 100. Larger values return 100

Both must be whole numbers; anything else returns 400. Keep requesting the next page while meta.pagination.hasMore is true.

Response

json

{
  "data": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "name": "Acme Corp",
      "description": "Managed since 2024",
      "color": "#0080dd",
      "contactEmail": "it@acme.example",
      "domainCount": 12,
      "createdAt": "2026-09-01T10:00:00.000Z",
      "updatedAt": "2026-09-01T10:00:00.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "hasMore": false
    }
  }
}

Example

bash

curl -H "Authorization: Bearer ms_your_token" \
  "https://app.mailshield.app/api/v1/customers?limit=100"

Create Customer

Add a customer to your organization.

POST /api/v1/customers

Request Body

Field	Type	Required	Description
`name`	string	Yes	1 to 100 characters, unique in your organization, ignoring case. Spaces at the start and end are removed
`description`	string	No	Up to 500 characters
`color`	string	No	A hex color as `#rrggbb`, such as `#0080dd`. Stored in lowercase
`contactEmail`	string	No	The address that gets the customer's scheduled reports

Any other field returns 400, so a typo such as contact_email doesn't go unnoticed.

Response (201 Created)

json

{
  "data": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "name": "Acme Corp",
    "description": null,
    "color": "#0080dd",
    "contactEmail": "it@acme.example",
    "domainCount": 0,
    "createdAt": "2026-09-01T10:00:00.000Z",
    "updatedAt": "2026-09-01T10:00:00.000Z"
  }
}

Example

bash

curl -X POST \
  -H "Authorization: Bearer ms_your_token" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corp", "color": "#0080dd", "contactEmail": "it@acme.example"}' \
  https://app.mailshield.app/api/v1/customers

Errors

400 - A missing or invalid field, an unknown field, or a body that isn't valid JSON
403 - The token is read-only
409 - There's already a customer with that name, ignoring case. The message names it, for example There's already a customer named "Acme Corp"

Get Customer

GET /api/v1/customers/{id}

Path Parameters

Parameter	Type	Description
`id`	uuid	Customer ID. An ID that isn't a UUID returns `404`

Response

json

{
  "data": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "name": "Acme Corp",
    "description": "Managed since 2024",
    "color": "#0080dd",
    "contactEmail": "it@acme.example",
    "domainCount": 12,
    "createdAt": "2026-09-01T10:00:00.000Z",
    "updatedAt": "2026-09-01T10:00:00.000Z"
  }
}

Example

bash

curl -H "Authorization: Bearer ms_your_token" \
  https://app.mailshield.app/api/v1/customers/7c9e6679-7425-40de-944b-e07fc1f90ae7

Errors

404 - Customer not found. Customers of other organizations aren't found either

Update Customer

Change a customer. Only the fields you send change.

PATCH /api/v1/customers/{id}

Path Parameters

Parameter	Type	Description
`id`	uuid	Customer ID

Request Body

Field	Type	Description
`name`	string	1 to 100 characters, unique in your organization, ignoring case. Changing only the capitalization of the customer's own name is fine
`description`	string or null	Up to 500 characters. `null` removes it
`color`	string or null	A hex color as `#rrggbb`. `null` removes it
`contactEmail`	string or null	`null` removes the contact

WARNING

Without a contact email, the customer's scheduled reports only go to their own recipients. A report that has no other recipients stops being sent.

A request that changes nothing returns the customer as it is, and updatedAt stays the same.

Response

json

{
  "data": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "name": "Acme Corporation",
    "description": "Managed since 2024",
    "color": "#0080dd",
    "contactEmail": "ops@acme.example",
    "domainCount": 12,
    "createdAt": "2026-09-01T10:00:00.000Z",
    "updatedAt": "2026-09-25T08:15:00.000Z"
  }
}

Example

bash

curl -X PATCH \
  -H "Authorization: Bearer ms_your_token" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corporation", "contactEmail": "ops@acme.example"}' \
  https://app.mailshield.app/api/v1/customers/7c9e6679-7425-40de-944b-e07fc1f90ae7

Errors

400 - An invalid field, an unknown field, or a body that isn't valid JSON
403 - The token is read-only
404 - Customer not found
409 - Another customer already has that name, ignoring case

Delete Customer

DELETE /api/v1/customers/{id}

Path Parameters

Parameter	Type	Description
`id`	uuid	Customer ID

Response

json

{
  "data": {
    "deleted": true
  }
}

Example

bash

curl -X DELETE \
  -H "Authorization: Bearer ms_your_token" \
  https://app.mailshield.app/api/v1/customers/7c9e6679-7425-40de-944b-e07fc1f90ae7

WARNING

This action cannot be undone. The customer's domains stay in your organization with their checks and reports, but no longer have a customer. The customer's scheduled reports are deleted.

Errors

403 - The token is read-only
404 - Customer not found

Assign Domains to a Customer

Assign a domain with Update Domain:

bash

curl -X PATCH \
  -H "Authorization: Bearer ms_your_token" \
  -H "Content-Type: application/json" \
  -d '{"customerId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"}' \
  https://app.mailshield.app/api/v1/domains/550e8400-e29b-41d4-a716-446655440000

Send "customerId": null to remove the domain from its customer. The customer must be in your organization; any other ID returns 400. Every domain response shows the assignment as customerId and customerName.

To list a customer's domains, filter List Domains by customerId. customerId=none lists the domains without a customer:

bash

curl -H "Authorization: Bearer ms_your_token" \
  "https://app.mailshield.app/api/v1/domains?customerId=7c9e6679-7425-40de-944b-e07fc1f90ae7"

Customers ​

The Customer Object ​

List Customers ​

Query Parameters ​

Response ​

Example ​

Create Customer ​

Request Body ​

Response (201 Created) ​

Example ​

Errors ​

Get Customer ​

Path Parameters ​

Response ​

Example ​

Errors ​

Update Customer ​

Path Parameters ​

Request Body ​

Response ​

Example ​

Errors ​

Delete Customer ​

Path Parameters ​

Response ​

Example ​

Errors ​

Assign Domains to a Customer ​

Customers

The Customer Object

List Customers

Query Parameters

Response

Example

Create Customer

Request Body

Response (201 Created)

Example

Errors

Get Customer

Path Parameters

Response

Example

Errors

Update Customer

Path Parameters

Request Body

Response

Example

Errors

Delete Customer

Path Parameters

Response

Example

Errors

Assign Domains to a Customer