Skip to main content
Add a person to the project’s address book. Contacts carry name, subscription state, and arbitrary metadata you can use in templates and reporting. POST /v1/contacts

​
Body

​
email
string
required
The contact’s email address. Unique within the project.
​
firstName
string
Given name.
​
lastName
string
Family name.
​
subscribed
boolean
Whether the contact is opted in. Defaults to true. When false, unsubscribedAt is stamped on create.
​
metadata
object
Free-form key/value pairs stored alongside the contact.
Subscription is not suppression. The subscribed flag is an app-level marketing signal. It does not block delivery — that’s the job of suppressions. A complaint still drops a message even if subscribed is true.

​
Request

curl https://api.drin.run/v1/contacts \
  -H "Authorization: Bearer $DRIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada@example.com",
    "firstName": "Ada",
    "lastName": "Lovelace",
    "metadata": { "plan": "pro" }
  }'

​
Response

Returns 201 Created with the contact. If a contact with the same email already exists in this project, the call returns 409 conflict (contact_email_taken).
201 Created
{
  "id": "ct_7Yh2Lp",
  "email": "ada@example.com",
  "firstName": "Ada",
  "lastName": "Lovelace",
  "subscribed": true,
  "unsubscribedAt": null,
  "metadata": { "plan": "pro" },
  "createdAt": "2026-06-02T17:30:00.000Z",
  "updatedAt": "2026-06-02T17:30:00.000Z"
}