Get recipient status

POST Stable

/v1/recipients/status

Use this endpoint to inspect whether an app can send notifications to a recipient and to display recent delivery state without exposing raw message bodies.

Request

Name	Type	Required	Description	Example
`Authorization`	string	Yes	Bearer API key for the EmailsDone environment.	`Bearer ed_...`
`email`	email	Yes	Recipient email address to inspect.	`user@example.com`
`limit`	number	No	Number of recent messages to return. Values are clamped between 1 and 50.	`10`

curl

curl -X POST 'https://api.emailsdone.dev/v1/recipients/status' \
  -H 'Authorization: Bearer ed_...' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "user@example.com",
  "limit": 10
}'

Response

Name	Type	Required	Description	Example
`ok`	boolean	Yes	True when recipient status was read.	`true`
`recipient.emailMasked`	string	Yes	Masked recipient email.	`u***@example.com`
`recipient.recipientDomain`	string	Yes	Recipient domain.	`example.com`
`recipient.state`	string	Yes	Recipient delivery/subscription state.	`clear`
`recipient.subscription.status`	string	Yes	Notification subscription status.	`subscribed`
`recipient.delivery.hardBounceCount`	number	Yes	Hard bounce count for this recipient.	`0`
`recipient.delivery.complaintCount`	number	Yes	Complaint count for this recipient.	`0`
`recipient.canSendNotifications`	boolean	Yes	Whether notification templates can currently be sent.	`true`
`messages`	array	Yes	Recent message metadata for this recipient.	`[]`

{
  "ok": true,
  "recipient": {
    "emailMasked": "u***@example.com",
    "recipientDomain": "example.com",
    "state": "clear",
    "subscription": {
      "scope": "app_notifications",
      "status": "subscribed",
      "unsubscribedAt": null,
      "resubscribedAt": null
    },
    "delivery": {
      "hardBounceCount": 0,
      "complaintCount": 0,
      "cooldownUntil": null,
      "complainedAt": null
    },
    "canSendNotifications": true
  },
  "messages": []
}

Errors

Status	Code	Message
400	`invalid_request`	Expected a valid recipient email.
401	`missing_api_key`	Authorization bearer token is missing.
401	`invalid_api_key`	API key is invalid.
402	`trial_expired`	The trial can no longer send email.
403	`api_key_revoked`	API key has been revoked.
403	`project_inactive`	Project is disabled by the current plan.
403	`environment_inactive`	Environment is disabled by the current plan.
404	`project_not_found`	Project not found for API key.
404	`environment_not_found`	Environment not found for API key.
405	`method_not_allowed`	Only POST is allowed.
500	`internal`	Unexpected server error.

Notes

This endpoint returns metadata only. It does not expose email content.
Use canSendNotifications before showing notification-specific controls.