Skip to content
Open Console →

Email

27 endpoints under /api/v1/email.

GET /api/v1/email/keys #

List send keys (metadata only — never a secret)

Responses

200 The org's send keys.
Response body
  • sendKeysEmailSendKey[]required
    Show fields
    • idstringrequired
    • namestringrequired
    • keyIdstringrequired
    • domainIdsstring[]required
    • createdAtstringrequired
    • lastUsedAtstring
401 No valid session.
Response body
  • errorstringrequired
403 Email is not enabled for this organization (private beta), or the acting subject lacks the required Email permission (possibly on this Domain).
Response body
  • errorstringrequired
404 Unknown resource (or content past its retention window).
Response body
  • errorstringrequired
502 The Email service is unreachable.
Response body
  • errorstringrequired
POST /api/v1/email/keys #

Mint a send key

The plaintext secret is returned ONCE. Minting a long-lived credential is admin-tier (email.key.admin) — org-wide for an unrestricted key.

Request body

  • namestringrequired
  • domainIdsstring[]

Responses

201 Key minted; the secret appears only here.
Response body
  • sendKeyobjectrequired
    Show fields
    • idstringrequired
    • namestringrequired
    • keyIdstringrequired
    • domainIdsstring[]required
    • createdAtstringrequired
    • lastUsedAtstring
  • secretstringrequired
401 No valid session.
Response body
  • errorstringrequired
403 Email is not enabled for this organization (private beta), or the acting subject lacks the required Email permission (possibly on this Domain).
Response body
  • errorstringrequired
404 Unknown resource (or content past its retention window).
Response body
  • errorstringrequired
502 The Email service is unreachable.
Response body
  • errorstringrequired
GET /api/v1/email/routes #

List inbound routes

Responses

200 The org's routes (instance-filtered for scoped subjects).
Response body
  • routesEmailRoute[]required
    Show fields
    • idstringrequired
    • domainIdstringrequired
    • patternstringrequired
    • endpointIdstringrequired
    • createdAtstringrequired
401 No valid session.
Response body
  • errorstringrequired
403 Email is not enabled for this organization (private beta), or the acting subject lacks the required Email permission (possibly on this Domain).
Response body
  • errorstringrequired
404 Unknown resource (or content past its retention window).
Response body
  • errorstringrequired
502 The Email service is unreachable.
Response body
  • errorstringrequired
POST /api/v1/email/routes #

Create an inbound route

Pattern is the local part: exact, trailing-star prefix, or '*'. The domain must be receive-armed; the endpoint must be the org's.

Request body

  • domainIdstringrequired
  • patternstringrequired
  • endpointIdstringrequired

Responses

201 Route created.
Response body
  • idstringrequired
  • domainIdstringrequired
  • patternstringrequired
  • endpointIdstringrequired
  • createdAtstringrequired
401 No valid session.
Response body
  • errorstringrequired
403 Email is not enabled for this organization (private beta), or the acting subject lacks the required Email permission (possibly on this Domain).
Response body
  • errorstringrequired
404 Unknown resource (or content past its retention window).
Response body
  • errorstringrequired
409 Pattern already exists on the domain, or receiving is not armed.
Response body
  • errorstringrequired
502 The Email service is unreachable.
Response body
  • errorstringrequired
GET /api/v1/email/domains #

List the org's Email domains

Responses

200 The org's domains (instance-filtered for scoped subjects).
Response body
  • domainsEmailDomain[]required
    Show fields
    • idstringrequired
    • namestringrequired
    • sendStatestring · enumrequired

      pendingverifiedfailed

    • receiveStatestring · enumrequired

      nonependingverifiedfailed

    • createdAtstringrequired
    • dnsRecordsEmailDnsRecord[]required
      Show fields
      • capabilitystring · enumrequired

        sendreceive

      • typestringrequired
      • namestringrequired
      • valuestringrequired
      • priorityinteger
401 No valid session.
Response body
  • errorstringrequired
403 Email is not enabled for this organization (private beta), or the acting subject lacks the required Email permission (possibly on this Domain).
Response body
  • errorstringrequired
404 Unknown resource (or content past its retention window).
Response body
  • errorstringrequired
502 The Email service is unreachable.
Response body
  • errorstringrequired
POST /api/v1/email/domains #

Register a domain

Returns the DNS records to publish. 409 when the name has a live claim anywhere (SES identities are account-global).

Request body

  • namestringrequired

Responses

201 Domain registered; publish the returned records.
Response body
  • idstringrequired
  • namestringrequired
  • sendStatestring · enumrequired

    pendingverifiedfailed

  • receiveStatestring · enumrequired

    nonependingverifiedfailed

  • createdAtstringrequired
  • dnsRecordsEmailDnsRecord[]required
    Show fields
    • capabilitystring · enumrequired

      sendreceive

    • typestringrequired
    • namestringrequired
    • valuestringrequired
    • priorityinteger
401 No valid session.
Response body
  • errorstringrequired
403 Email is not enabled for this organization (private beta), or the acting subject lacks the required Email permission (possibly on this Domain).
Response body
  • errorstringrequired
404 Unknown resource (or content past its retention window).
Response body
  • errorstringrequired
409 The domain already has a live claim.
Response body
  • errorstringrequired
502 The Email service is unreachable.
Response body
  • errorstringrequired
GET /api/v1/email/webhooks #

List webhook endpoints

Responses

200 The org's endpoints.
Response body
  • webhooksEmailWebhook[]required
    Show fields
    • idstringrequired
    • urlstringrequired
    • eventTypesstring[]required
    • disabledbooleanrequired
    • createdAtstringrequired
401 No valid session.
Response body
  • errorstringrequired
403 Email is not enabled for this organization (private beta), or the acting subject lacks the required Email permission (possibly on this Domain).
Response body
  • errorstringrequired
404 Unknown resource (or content past its retention window).
Response body
  • errorstringrequired
502 The Email service is unreachable.
Response body
  • errorstringrequired
GET /api/v1/email/messages #

The message log (metadata; 90-day window)

Parameters

  • direction query string · enum
  • state query string
  • domainId query string
  • to query string
  • since query string
  • cursor query string

Responses

200 One page, newest first; pass `cursor` back for the next.
Response body
  • messagesEmailMessage[]required
    Show fields
    • idstringrequired
    • directionstring · enumrequired

      sendreceive

    • statestringrequired
    • fromstringrequired
    • tostring[]required
    • ccstring[]
    • subjectstring
    • sizeBytesintegerrequired
    • doorstring
    • domainIdstringrequired
    • lastErrorstring
    • createdAtstringrequired
    • sentAtstring
    • stateAtstringrequired
  • cursorstring
401 No valid session.
Response body
  • errorstringrequired
403 Email is not enabled for this organization (private beta), or the acting subject lacks the required Email permission (possibly on this Domain).
Response body
  • errorstringrequired
404 Unknown resource (or content past its retention window).
Response body
  • errorstringrequired
502 The Email service is unreachable.
Response body
  • errorstringrequired
GET /api/v1/email/settings #

The org's sending posture (read-only)

Quota raises and unpause are staff actions (ADR 0049 §6) — there is deliberately no org-side settings write.

Responses

200 The posture.
Response body
  • dailyQuotaintegerrequired
  • pausedbooleanrequired
  • pausedAtstring
  • pauseReasonstring
  • bouncePausePctnumber
  • complaintPausePctnumber
  • acceptedTodayinteger
401 No valid session.
Response body
  • errorstringrequired
403 Email is not enabled for this organization (private beta), or the acting subject lacks the required Email permission (possibly on this Domain).
Response body
  • errorstringrequired
404 Unknown resource (or content past its retention window).
Response body
  • errorstringrequired
502 The Email service is unreachable.
Response body
  • errorstringrequired
POST /api/v1/email/webhooks #

Create a webhook endpoint

The signing secret is returned ONCE (rotate for a new one).

Request body

  • urlstring · urirequired
  • eventTypesstring · enum[]required

Responses

201 Endpoint created; the signing secret appears only here.
Response body
  • webhookobjectrequired
    Show fields
    • idstringrequired
    • urlstringrequired
    • eventTypesstring[]required
    • disabledbooleanrequired
    • createdAtstringrequired
  • signingSecretstringrequired
401 No valid session.
Response body
  • errorstringrequired
403 Email is not enabled for this organization (private beta), or the acting subject lacks the required Email permission (possibly on this Domain).
Response body
  • errorstringrequired
404 Unknown resource (or content past its retention window).
Response body
  • errorstringrequired
502 The Email service is unreachable.
Response body
  • errorstringrequired
DELETE /api/v1/email/keys/{id} #

Revoke a send key

Parameters

  • id path string required

Responses

204 Revoked (tombstoned).
401 No valid session.
Response body
  • errorstringrequired
403 Email is not enabled for this organization (private beta), or the acting subject lacks the required Email permission (possibly on this Domain).
Response body
  • errorstringrequired
404 Unknown resource (or content past its retention window).
Response body
  • errorstringrequired
502 The Email service is unreachable.
Response body
  • errorstringrequired
DELETE /api/v1/email/routes/{id} #

Delete an inbound route

Parameters

  • id path string required

Responses

204 Deleted.
401 No valid session.
Response body
  • errorstringrequired
403 Email is not enabled for this organization (private beta), or the acting subject lacks the required Email permission (possibly on this Domain).
Response body
  • errorstringrequired
404 Unknown resource (or content past its retention window).
Response body
  • errorstringrequired
502 The Email service is unreachable.
Response body
  • errorstringrequired
GET /api/v1/email/domains/{id} #

One domain, with its DNS records

Parameters

  • id path string required

Responses

200 The domain.
Response body
  • idstringrequired
  • namestringrequired
  • sendStatestring · enumrequired

    pendingverifiedfailed

  • receiveStatestring · enumrequired

    nonependingverifiedfailed

  • createdAtstringrequired
  • dnsRecordsEmailDnsRecord[]required
    Show fields
    • capabilitystring · enumrequired

      sendreceive

    • typestringrequired
    • namestringrequired
    • valuestringrequired
    • priorityinteger
401 No valid session.
Response body
  • errorstringrequired
403 Email is not enabled for this organization (private beta), or the acting subject lacks the required Email permission (possibly on this Domain).
Response body
  • errorstringrequired
404 Unknown resource (or content past its retention window).
Response body
  • errorstringrequired
502 The Email service is unreachable.
Response body
  • errorstringrequired
GET /api/v1/email/suppressions #

The org's suppression list

Responses

200 Suppressed recipients.
Response body
  • suppressionsEmailSuppression[]required
    Show fields
    • idstringrequired
    • addressstringrequired
    • reasonstring · enumrequired

      bouncecomplaintmanual

    • createdAtstringrequired
401 No valid session.
Response body
  • errorstringrequired
403 Email is not enabled for this organization (private beta), or the acting subject lacks the required Email permission (possibly on this Domain).
Response body
  • errorstringrequired
404 Unknown resource (or content past its retention window).
Response body
  • errorstringrequired
502 The Email service is unreachable.
Response body
  • errorstringrequired
POST /api/v1/email/suppressions #

Suppress an address (manual)

Request body

  • addressstringrequired

Responses

201 Suppressed.
Response body
  • idstringrequired
  • addressstringrequired
  • reasonstring · enumrequired

    bouncecomplaintmanual

  • createdAtstringrequired
401 No valid session.
Response body
  • errorstringrequired
403 Email is not enabled for this organization (private beta), or the acting subject lacks the required Email permission (possibly on this Domain).
Response body
  • errorstringrequired
404 Unknown resource (or content past its retention window).
Response body
  • errorstringrequired
502 The Email service is unreachable.
Response body
  • errorstringrequired
DELETE /api/v1/email/domains/{id} #

Delete a domain

Parameters

  • id path string required

Responses

204 Deleted (SES identity cleared best-effort).
401 No valid session.
Response body
  • errorstringrequired
403 Email is not enabled for this organization (private beta), or the acting subject lacks the required Email permission (possibly on this Domain).
Response body
  • errorstringrequired
404 Unknown resource (or content past its retention window).
Response body
  • errorstringrequired
502 The Email service is unreachable.
Response body
  • errorstringrequired
GET /api/v1/email/messages/{id} #

One message, with its delivery events

Parameters

  • id path string required

Responses

200 The message.
Response body
  • messageobjectrequired
    Show fields
    • idstringrequired
    • directionstring · enumrequired

      sendreceive

    • statestringrequired
    • fromstringrequired
    • tostring[]required
    • ccstring[]
    • subjectstring
    • sizeBytesintegerrequired
    • doorstring
    • domainIdstringrequired
    • lastErrorstring
    • createdAtstringrequired
    • sentAtstring
    • stateAtstringrequired
  • eventsEmailMessageEvent[]required
    Show fields
    • kindstring · enumrequired

      sentdeliveredbouncedcomplained

    • bounceTypestring
    • recipientstring
    • detailobject
    • occurredAtstringrequired
401 No valid session.
Response body
  • errorstringrequired
403 Email is not enabled for this organization (private beta), or the acting subject lacks the required Email permission (possibly on this Domain).
Response body
  • errorstringrequired
404 Unknown resource (or content past its retention window).
Response body
  • errorstringrequired
502 The Email service is unreachable.
Response body
  • errorstringrequired
PATCH /api/v1/email/webhooks/{id} #

Update a webhook endpoint

Parameters

  • id path string required

Request body

  • urlstring · uri
  • eventTypesstring · enum[]
  • disabledboolean

Responses

200 Updated.
Response body
  • idstringrequired
  • urlstringrequired
  • eventTypesstring[]required
  • disabledbooleanrequired
  • createdAtstringrequired
401 No valid session.
Response body
  • errorstringrequired
403 Email is not enabled for this organization (private beta), or the acting subject lacks the required Email permission (possibly on this Domain).
Response body
  • errorstringrequired
404 Unknown resource (or content past its retention window).
Response body
  • errorstringrequired
502 The Email service is unreachable.
Response body
  • errorstringrequired
DELETE /api/v1/email/webhooks/{id} #

Delete a webhook endpoint

Parameters

  • id path string required

Responses

204 Deleted.
401 No valid session.
Response body
  • errorstringrequired
403 Email is not enabled for this organization (private beta), or the acting subject lacks the required Email permission (possibly on this Domain).
Response body
  • errorstringrequired
404 Unknown resource (or content past its retention window).
Response body
  • errorstringrequired
409 An inbound route still targets this endpoint.
Response body
  • errorstringrequired
502 The Email service is unreachable.
Response body
  • errorstringrequired
GET /api/v1/email/domains/{id}/dns #

Observe which DNS records are live (debugging)

For each expected record, whether it currently resolves — found, missing, mismatch (with the observed value), or error. Distinct from the domain's SES verification state, which this helps explain.

Parameters

  • id path string required

Responses

200 One observation per expected record.
Response body
  • recordsobject[]required
401 No valid session.
Response body
  • errorstringrequired
403 Email is not enabled for this organization (private beta), or the acting subject lacks the required Email permission (possibly on this Domain).
Response body
  • errorstringrequired
404 Unknown resource (or content past its retention window).
Response body
  • errorstringrequired
502 The Email service is unreachable.
Response body
  • errorstringrequired
DELETE /api/v1/email/suppressions/{id} #

Remove a suppression (the address becomes deliverable again)

Parameters

  • id path string required

Responses

204 Removed — the next hard bounce re-adds it.
401 No valid session.
Response body
  • errorstringrequired
403 Email is not enabled for this organization (private beta), or the acting subject lacks the required Email permission (possibly on this Domain).
Response body
  • errorstringrequired
404 Unknown resource (or content past its retention window).
Response body
  • errorstringrequired
502 The Email service is unreachable.
Response body
  • errorstringrequired
GET /api/v1/email/webhook-deliveries #

Recent webhook deliveries

Parameters

  • messageId query string
  • endpointId query string

Responses

200 Deliveries, newest first.
Response body
  • deliveriesEmailDelivery[]required
    Show fields
    • idintegerrequired
    • endpointIdstringrequired
    • eventTypestringrequired
    • messageIdstring
    • statestring · enumrequired

      pendingdeliveringdeliveredfailed

    • attemptsintegerrequired
    • lastStatusinteger
    • lastErrorstring
    • deliveredAtstring
    • createdAtstringrequired
401 No valid session.
Response body
  • errorstringrequired
403 Email is not enabled for this organization (private beta), or the acting subject lacks the required Email permission (possibly on this Domain).
Response body
  • errorstringrequired
404 Unknown resource (or content past its retention window).
Response body
  • errorstringrequired
502 The Email service is unreachable.
Response body
  • errorstringrequired
POST /api/v1/email/domains/{id}/check #

Force a verification pass

Parameters

  • id path string required

Responses

202 Check scheduled.
Response body
  • statusstringrequired
401 No valid session.
Response body
  • errorstringrequired
403 Email is not enabled for this organization (private beta), or the acting subject lacks the required Email permission (possibly on this Domain).
Response body
  • errorstringrequired
404 Unknown resource (or content past its retention window).
Response body
  • errorstringrequired
502 The Email service is unreachable.
Response body
  • errorstringrequired
POST /api/v1/email/domains/{id}/receive #

Arm receiving on a domain

Receiving MX is EXCLUSIVE — pointing a mailbox domain's MX at the platform breaks its existing mail. Arm a dedicated subdomain.

Parameters

  • id path string required

Responses

200 Receiving armed; publish the MX record.
Response body
  • idstringrequired
  • namestringrequired
  • sendStatestring · enumrequired

    pendingverifiedfailed

  • receiveStatestring · enumrequired

    nonependingverifiedfailed

  • createdAtstringrequired
  • dnsRecordsEmailDnsRecord[]required
    Show fields
    • capabilitystring · enumrequired

      sendreceive

    • typestringrequired
    • namestringrequired
    • valuestringrequired
    • priorityinteger
401 No valid session.
Response body
  • errorstringrequired
403 Email is not enabled for this organization (private beta), or the acting subject lacks the required Email permission (possibly on this Domain).
Response body
  • errorstringrequired
404 Unknown resource (or content past its retention window).
Response body
  • errorstringrequired
502 The Email service is unreachable.
Response body
  • errorstringrequired
GET /api/v1/email/messages/{id}/content #

The raw message (message/rfc822; 30-day window)

Parameters

  • id path string required

Responses

200 The raw MIME, streamed.
401 No valid session.
Response body
  • errorstringrequired
403 Email is not enabled for this organization (private beta), or the acting subject lacks the required Email permission (possibly on this Domain).
Response body
  • errorstringrequired
404 Unknown resource (or content past its retention window).
Response body
  • errorstringrequired
502 The Email service is unreachable.
Response body
  • errorstringrequired
POST /api/v1/email/webhooks/{id}/rotate-secret #

Rotate the signing secret

The NEW secret is returned once; the old stops signing immediately.

Parameters

  • id path string required

Responses

200 Rotated.
Response body
  • signingSecretstringrequired
401 No valid session.
Response body
  • errorstringrequired
403 Email is not enabled for this organization (private beta), or the acting subject lacks the required Email permission (possibly on this Domain).
Response body
  • errorstringrequired
404 Unknown resource (or content past its retention window).
Response body
  • errorstringrequired
502 The Email service is unreachable.
Response body
  • errorstringrequired
POST /api/v1/email/webhook-deliveries/{id}/redeliver #

Redeliver a webhook payload

Inserts a NEW delivery row from the frozen payload.

Parameters

  • id path integer

Responses

202 Redelivery queued.
Response body
  • idintegerrequired
401 No valid session.
Response body
  • errorstringrequired
403 Email is not enabled for this organization (private beta), or the acting subject lacks the required Email permission (possibly on this Domain).
Response body
  • errorstringrequired
404 Unknown resource (or content past its retention window).
Response body
  • errorstringrequired
502 The Email service is unreachable.
Response body
  • errorstringrequired