Skip to main content
POST
/
api
/
v1
/
subscribers
/
{email}
/
consents
Grant consent for a topic
curl --request POST \
  --url https://api.railmail.app/api/v1/subscribers/{email}/consents \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "topicKey": "APIT-1",
  "source": "preference-center",
  "ipAddress": "203.0.113.10",
  "userAgent": "Mozilla/5.0",
  "sourceUrl": "https://shop.example.com/prefs",
  "consentText": "I agree to receive the newsletter",
  "formVersion": "v3"
}
'
{
  "topicKey": "APIT-1",
  "status": "PENDING_CONFIRMATION",
  "requiresConfirmation": true,
  "grantedAt": "2026-06-24T10:20:00Z",
  "confirmedAt": null,
  "tokenExpiresAt": "2026-06-26T10:20:00Z"
}

Authorizations

​
X-API-Key
string
header
required

Project-scoped API key, format rm_(live|test)_... . May also be sent as Authorization: Bearer rm_....

Path Parameters

​
email
string<email>
required

URL-encoded subscriber email.

Body

application/json
​
topicKey
string
required
​
source
string
required
​
ipAddress
string | null
​
userAgent
string | null
​
sourceUrl
string | null
​
consentText
string | null
​
formVersion
string | null

Response

Consent granted (or pending confirmation for double opt-in topics)

When requiresConfirmation is true, the topic uses double opt-in and the subscriber must confirm via email before they are subscribed.

​
topicKey
string
​
status
string

e.g. SUBSCRIBED, PENDING_CONFIRMATION, UNSUBSCRIBED.

​
requiresConfirmation
boolean
​
grantedAt
string<date-time> | null
​
confirmedAt
string<date-time> | null
​
tokenExpiresAt
string<date-time> | null