Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/DataTalksClub/datamailer/llms.txt

Use this file to discover all available pages before exploring further.

GET /api/contacts/status lets your application check exactly what Datamailer knows about a contact before sending email, showing a confirmation screen, or updating UI state. The response includes every field that determines whether a marketing or transactional send will succeed.

​
Endpoint

GET /api/contacts/status

​
Authentication

Requires a Bearer token for the client whose slug is passed as the client query parameter. 
Authorization: Bearer <client-api-key>

​
Query parameters

​
email
string
required
The email address to look up. Normalized to lowercase before matching.
​
audience
string
required
Slug of the audience to scope the subscription lookup to. Must belong to the authenticated client’s organization.
​
client
string
required
Slug of the authenticated client. Must exactly match the bearer token’s client.

​
Response

Returns HTTP 200 in all cases, including when the contact does not exist or is not visible to the authenticated client scope. Check exists before relying on other fields.
​
contact_id
integer | null
Internal Datamailer ID for the contact, or null when exists is false.
​
email
string
Normalized (lowercased) email address. Returns the requested email when exists is false.
​
exists
boolean
true only when a contact record exists and the authenticated client has a subscription record for that contact in this audience. Returns false and zeroed state otherwise, hiding whether a contact exists at all outside this client’s scope.
​
verified
boolean
Whether the contact has a verified_at timestamp at the contact level.
​
verified_at
string | null
ISO-8601 UTC timestamp of contact-level verification, or null.
​
email_validation
object
Current email validation state. All fields return zero values when exists is false.
​
global_unsubscribed
boolean
Whether the contact has opted out of all marketing email globally.
​
hard_bounced
boolean
Whether the contact’s address has hard bounced.
​
complained
boolean
Whether the contact has filed a spam complaint.
​
audience
object
Audience-scoped subscription state.
​
client
object
Client-scoped subscription state. Same shape as audience.
​
can_send_marketing
boolean
Whether a marketing campaign email can currently be sent to this contact for this audience and client. false if the contact is suppressed, has a non-deliverable email validation status, is not subscribed, or has not passed verification on any subscription level.
​
can_send_transactional
boolean
Whether a transactional email can currently be sent to this contact. false only if the contact has hard bounced or complained.

​
Example

​
Request

curl "https://datamailer.example.com/api/contacts/status?email=learner%40example.com&audience=dtc-courses&client=dtc-courses" \
  -H "Authorization: Bearer dm_dtccourses_demo_transactional_email_key"

​
Response — contact found

{
  "contact_id": 42,
  "email": "learner@example.com",
  "exists": true,
  "verified": true,
  "verified_at": "2024-09-01T10:00:00Z",
  "email_validation": {
    "status": "externally_validated",
    "reason": "client signup validation",
    "validated_at": "2024-09-01T10:00:00Z"
  },
  "global_unsubscribed": false,
  "hard_bounced": false,
  "complained": false,
  "audience": {
    "slug": "dtc-courses",
    "subscribed": false,
    "status": null,
    "verified": false,
    "verified_at": null,
    "unsubscribed_at": null,
    "unsubscribe_reason": ""
  },
  "client": {
    "slug": "dtc-courses",
    "subscribed": true,
    "status": "subscribed",
    "verified": true,
    "verified_at": "2024-09-01T10:00:00Z",
    "unsubscribed_at": null,
    "unsubscribe_reason": ""
  },
  "can_send_marketing": true,
  "can_send_transactional": true
}

​
Response — contact not visible to this client

{
  "contact_id": null,
  "email": "unknown@example.com",
  "exists": false,
  "verified": false,
  "verified_at": null,
  "email_validation": {
    "status": "unknown",
    "reason": "",
    "validated_at": null
  },
  "global_unsubscribed": false,
  "hard_bounced": false,
  "complained": false,
  "audience": {
    "slug": "dtc-courses",
    "subscribed": false,
    "status": null,
    "verified": false,
    "verified_at": null,
    "unsubscribed_at": null,
    "unsubscribe_reason": ""
  },
  "client": {
    "slug": "dtc-courses",
    "subscribed": false,
    "status": null,
    "verified": false,
    "verified_at": null,
    "unsubscribed_at": null,
    "unsubscribe_reason": ""
  },
  "can_send_marketing": false,
  "can_send_transactional": false
}
Privacy scoping: if a contact exists in Datamailer but has no subscription record for the requested client within this audience, the response returns exists: false with all zeroed state. This prevents one client from discovering whether an email address belongs to another client’s subscriber list.

Build docs developers (and LLMs) love

Get started for freeTalk to us