Email

Every /v1 route for email. This page is generated from the API's OpenAPI contract, so it always matches what the API accepts and returns.

Authentication, pagination, errors and idempotency work the same on every route. They are described once, in the API overview.

A workspace's sending domains

GET /v1/workspaces/{workspaceId}/mail/domains

Key scopes: READ and EMAIL_SEND.

Path parameters

Name	Type	Required	Notes
`workspaceId`	`string`	yes	The workspace's id.

Query parameters

Name	Type	Required	Notes
`limit`	`integer`	no	Rows per page. Ignored when a cursor is given.
`cursor`	`string`	no	The `nextCursor` of the previous page, unchanged.

Returns

200 with a page: { data: V1MailDomain[], nextCursor }, where each item is V1MailDomain.

bash

curl "https://api.naijacloud.com/v1/workspaces/$WORKSPACE_ID/mail/domains" \
  -H "Authorization: Bearer $NC_API_KEY"

Add a sending domain

POST /v1/workspaces/{workspaceId}/mail/domains

Returns the DNS records to publish, then verify it.

Key scopes: WRITE and EMAIL_SEND.

Path parameters

Name	Type	Required	Notes
`workspaceId`	`string`	yes	The workspace's id.

Headers

Name	Type	Required	Notes
`Idempotency-Key`	`string`	no	Any unique string (1–255 printable characters). A retry with the same key and body returns the first response instead of acting twice, for 24 hours.

Body

Field	Type	Required	Notes
`name`	`string`	yes	e.g. `mail.acme.ng`
`region`	`string`	no	e.g. `eu-west`

Returns

201 with V1MailDomainDetail.

bash

curl -X POST "https://api.naijacloud.com/v1/workspaces/$WORKSPACE_ID/mail/domains" \
  -H "Authorization: Bearer $NC_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"mail.acme.ng"}'

A workspace's mail keys (hints only, never the key)

GET /v1/workspaces/{workspaceId}/mail/keys

Key scopes: READ and EMAIL_SEND.

Path parameters

Name	Type	Required	Notes
`workspaceId`	`string`	yes	The workspace's id.

Query parameters

Name	Type	Required	Notes
`limit`	`integer`	no	Rows per page. Ignored when a cursor is given.
`cursor`	`string`	no	The `nextCursor` of the previous page, unchanged.

Returns

200 with a page: { data: V1MailApiKey[], nextCursor }, where each item is V1MailApiKey.

bash

curl "https://api.naijacloud.com/v1/workspaces/$WORKSPACE_ID/mail/keys" \
  -H "Authorization: Bearer $NC_API_KEY"

A sending domain with its DNS records

GET /v1/workspaces/{workspaceId}/mail/domains/{domainId}

Key scopes: READ and EMAIL_SEND.

Path parameters

Name	Type	Required	Notes
`workspaceId`	`string`	yes	The workspace's id.
`domainId`	`string`	yes	The domain's id.

Returns

200 with V1MailDomainDetail.

bash

curl "https://api.naijacloud.com/v1/workspaces/$WORKSPACE_ID/mail/domains/$DOMAIN_ID" \
  -H "Authorization: Bearer $NC_API_KEY"

Remove a sending domain

DELETE /v1/workspaces/{workspaceId}/mail/domains/{domainId}

Key scopes: WRITE and EMAIL_SEND.

Path parameters

Name	Type	Required	Notes
`workspaceId`	`string`	yes	The workspace's id.
`domainId`	`string`	yes	The domain's id.

Returns

204 with no body.

bash

curl -X DELETE "https://api.naijacloud.com/v1/workspaces/$WORKSPACE_ID/mail/domains/$DOMAIN_ID" \
  -H "Authorization: Bearer $NC_API_KEY"

Check a sending domain's DNS records now

POST /v1/workspaces/{workspaceId}/mail/domains/{domainId}/verify

Key scopes: WRITE and EMAIL_SEND.

Path parameters

Name	Type	Required	Notes
`workspaceId`	`string`	yes	The workspace's id.
`domainId`	`string`	yes	The domain's id.

Returns

200 with V1MailDomainDetail.

bash

curl -X POST "https://api.naijacloud.com/v1/workspaces/$WORKSPACE_ID/mail/domains/$DOMAIN_ID/verify" \
  -H "Authorization: Bearer $NC_API_KEY"

Types

V1MailApiKey

Field	Type	Notes
`createdAt`	`string (date-time)`
`id`	`string`
`isLive`	`boolean`
`keyHint`	`string`	First characters of the key, to identify it in a list.
`lastUsedAt`	`string (date-time)`, or `null`
`name`	`string`
`revokedAt`	`string (date-time)`, or `null`
`scope`	`FULL`, `SEND`
`updatedAt`	`string (date-time)`

V1MailDnsRecord

Field	Type	Notes
`fqdn`	`string`	The full DNS name this record must exist at, e.g. nm._domainkey.send.acme.com.
`host`	`string`	Host relative to the sending domain; "@" is the sending domain itself.
`name`	`string`
`priority`	`number`, or `null`
`problem`	`string`, or `null`
`required`	`boolean`
`type`	`string`
`value`	`string`
`verified`	`boolean`
`zoneHost`	`string`, or `null`	Host relative to the DNS zone the customer edits (MailDomainDetail.zone); "@" is the zone root.

V1MailDnsZone

Field	Type	Notes
`dnsZoneId`	`string`, or `null`	The Naijacloud DNS zone id, when hostedOnNaijacloud.
`hostedOnNaijacloud`	`boolean`	True when this zone is on Naijacloud DNS in the same workspace, so publishMailDomainRecords can add the records in one step.
`name`	`string`	The zone the records are added to, e.g. acme.com for send.acme.com. zoneHost on each record is relative to it.

V1MailDomain

Field	Type	Notes
`createdAt`	`string (date-time)`
`dailyQuota`	`integer`
`dkimPublicKey`	`string`
`failingRecords`	array of `string`, or `null`
`id`	`string`
`lastCheckedAt`	`string (date-time)`, or `null`
`name`	`string`
`region`	`string`
`status`	`BROKEN`, `PENDING`, `SUSPENDED`, `VERIFIED`
`suspendedAt`	`string (date-time)`, or `null`
`suspendedReason`	`string`, or `null`
`updatedAt`	`string (date-time)`
`verifiedAt`	`string (date-time)`, or `null`

V1MailDomainDetail

Field	Type	Notes
`alignmentWarning`	`string`, or `null`	Set when the customer DMARC policy would break signing.
`domain`	`V1MailDomain`
`propagating`	`boolean`, or `null`	Set when DNS is right but not yet propagated.
`records`	array of `V1MailDnsRecord`
`zone`	`V1MailDnsZone`, or `null`	The DNS zone the records go into; each record carries zoneHost relative to it.