URIports API
The URIports API lets you manage monitored domains and access DMARC monitoring status. API access is available on the Stone plan and higher.
Table of Contents
- Base URL
- Authentication
- Quick Start
- Rate Limits
- Request Format
- Response Format
- Endpoints
- DMARC Status
- Domains
- Domain Groups
- Error Codes
- Support
Base URL
https://app.uriports.com/api/v1
Authentication
The API uses API keys for authentication.
API keys can be created by account owners in the URIports settings under Settings → API Keys.
Include the key in the Authorization header using the Bearer scheme.
Example
Authorization: Bearer urp_xxxxxxxx.yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
Notes
- API keys must be kept confidential and should never be shared.
- Once an API key has been created, it cannot be viewed or retrieved again.
- You can create multiple API keys for different systems or integrations.
- API keys can be disabled or deleted at any time.
- Only the account owner can manage API keys. Team members, including those with admin privileges, do not have access to API key management.
Quick Start
You can test the API immediately using a single command.
curl https://app.uriports.com/api/v1/dmarc \
-H "Authorization: Bearer YOUR_API_KEY"Example response:
{
"success": true,
"data": [
{
"domain": "example.com",
"p": "reject",
"sp": "reject",
"np": "reject",
"pct": 100,
"testing": "n",
"dmarc": 100.0,
"dkim": 100.0,
"spf": 100.0,
"count": 4
}
]
}Replace YOUR_API_KEY with the API key generated in your URIports settings.
Rate Limits
API requests are rate limited to ensure fair use and system stability. New API keys have a one-week grace period with higher rate limits.
| Endpoint | Limit |
|---|---|
/dmarc |
10 requests per hour |
/domains |
30 requests per hour |
/domaingroups |
100 requests per hour |
The API returns rate limit headers:
X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset
Example:
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 28
X-RateLimit-Reset: 1710003600
Request Format
Requests that send data must use JSON.
Header:
Content-Type: application/json
Rules:
- The request body must be a JSON object
Response Format
All API responses use the same structure.
Success response
{
"success": true,
"data": { }
}
Error response
{
"success": false,
"error": {
"code": "invalid_json",
"message": "Request body must contain valid JSON."
}
}
Each response also includes a request identifier header:
X-Request-Id
This identifier can be used when contacting support.
Endpoints
DMARC Status
GET /api/v1/dmarc
Returns DMARC monitoring status for all monitored domains.
Example
curl https://app.uriports.com/api/v1/dmarc \
-H "Authorization: Bearer YOUR_API_KEY"
Example response
{
"success": true,
"data": [
{
"domain": "example.com",
"p": "reject",
"sp": "reject",
"np": "reject",
"pct": 100,
"testing": "n",
"dmarc": 100.0,
"dkim": 100.0,
"spf": 100.0,
"count": 4
}
]
}Fields:
| Field | Description |
|---|---|
| domain | monitored domain |
| p | policy |
| sp | subdomain policy |
| np | non-existent subdomain policy |
| pct | policy percentage (deprecated) |
| testing | test mode |
| dmarc | DMARC alignment percentage |
| dkim | DKIM alignment percentage |
| spf | SPF alignment percentage |
| count | email volume |
DMARC data updates daily based on incoming reports, so retrieving it more than once per day is redundant.
Domain
GET /api/v1/domains
Returns all monitored domains in the account.
Example
curl https://app.uriports.com/api/v1/domains \
-H "Authorization: Bearer YOUR_API_KEY"
Example response
{
"success": true,
"data": {
"domains": [
"example.com",
"example.org"
]
}
}
POST /api/v1/domains
Adds one or more domains to the monitored domain list.
Example request body
{
"domains": [
"example.com",
"example.org"
]
}
Example request
curl https://app.uriports.com/api/v1/domains \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"domains":["example.com","example.org"]}'
Example response
{
"success": true,
"data": {
"message": "Domains added successfully. Background processing has started.",
"domains": [
"example.com",
"example.org"
],
"count": 2
}
}
Notes
- Domains must be valid hostnames.
- Duplicate domains are rejected.
- A maximum of 50 domains may be submitted per request.
DELETE /api/v1/domains
Removes one or more monitored domains.
Example request body
{
"domains": [
"example.com"
]
}
Example request
curl https://app.uriports.com/api/v1/domains \
-X DELETE \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"domains":["example.com"]}'
Example response
{
"success": true,
"data": {
"message": "Domains deleted successfully.",
"domains": [
"example.com"
],
"count": 1
}
}Notes
A domain cannot be removed if it is still actively used in certain monitoring features. You'll receive errors when this is the case.
Domain Groups
GET /api/v1/domaingroups
Returns all domain groups in the account, or a single group when an id is given.
Example
curl https://app.uriports.com/api/v1/domaingroups \
-H "Authorization: Bearer YOUR_API_KEY"Example response
{
"success": true,
"data": {
"groups": [
{
"id": "83839e94",
"name": "Production",
"domains": ["example.com", "example.org"]
}
],
"count": 1
}
}To fetch a single group, add an id query parameter:
curl "https://app.uriports.com/api/v1/domaingroups?id=83839e94" \
-H "Authorization: Bearer YOUR_API_KEY"{
"success": true,
"data": {
"group": {
"id": "83839e94",
"name": "Production",
"domains": ["example.com", "example.org"]
}
}
}POST /api/v1/domaingroups
Creates a new domain group. domains is optional, when included, the group is created with those members in the same call.
Example request body
{
"name": "Production",
"domains": ["example.com", "example.org"]
}Example request
curl https://app.uriports.com/api/v1/domaingroups \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Production","domains":["example.com","example.org"]}'Example response
{
"success": true,
"data": {
"group": {
"id": "83839e94",
"name": "Production",
"domains": ["example.com", "example.org"]
}
}
}Notes
- Group names must be unique within your account (case-insensitive).
- Group names are limited to 100 characters.
- All
domainsmust already be in your monitored domain list. If any domain isn't monitored, the request fails and no group is created.
PATCH /api/v1/domaingroups
Modifies an existing domain group. Requires the id query parameter. Supports full replacement of domains or incremental add/remove operations.
Request fields:
| Field | Type | Required | Description |
|---|---|---|---|
name |
string | no | New group name (max 100 chars, must be unique) |
domains |
array | no | Full replacement of group members |
add_domains |
array | no | Domains to add without touching existing members |
remove_domains |
array | no | Domains to remove; unrecognised entries are silently ignored |
At least one field must be provided. domains cannot be combined with add_domains or remove_domains. When add_domains and remove_domains are used together, adds are applied first.
Examples
Request
curl "https://app.uriports.com/api/v1/domaingroups?id=83839e94" \
-X PATCH \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"domains":["example.com"]}'Rename a group:
{
"name": "Production EU"
}
Full replace of members:
{
"domains": [
"example.com",
"example.nl"
]
}Add one domain without touching the rest:
{
"add_domains": [
"newdomain.com"
]
}Swap one domain for another in a single call:
{
"add_domains": [
"new.example.com"
],
"remove_domains": [
"old.example.com"
]
}DELETE /api/v1/domaingroups
Deletes a domain group. Requires an id query parameter. The domains themselves are not removed from your account, only the grouping.
Example request
curl "https://app.uriports.com/api/v1/domaingroups?id=83839e94" \
-X DELETE \
-H "Authorization: Bearer YOUR_API_KEY"Example response
{
"success": true,
"data": {
"message": "Domain group deleted successfully."
}
}Error Codes
Common API errors.
| Code | Meaning |
|---|---|
| unauthorized | Invalid or missing API key |
| rate_limited | Too many requests |
| invalid_json | Request body contains invalid JSON |
| invalid_request_body | Request body missing or unreadable |
| unknown_field | Request contains unsupported fields |
| missing_field | Required field missing |
| invalid_field_type | Field has incorrect type |
| invalid_domain | Domain syntax invalid |
| domain_delete_failed | Domain could not be removed |
| request_too_large | The request body is too large |
| duplicate_name | A group with that name already exists |
| not_monitored | One or more domains aren't in your monitored domain list |
| no_fields_to_update | PATCH request had neither name nor domains |
| conflicting_fields | domains was sent together with add_domains or remove_domains |
| not_found | Domain group id doesn't exist |
| missing_id | id query parameter required for PATCH/DELETE |
| invalid_name | Group name is empty or exceeds 100 characters |
Support
If you encounter issues using the API:
- Verify your API key is valid
- Check the rate limit headers
- Use the
X-Request-Idwhen contacting support
For further assistance please contact URIports support.