Docs
DashboardGet API key
API · contacts

Create a contact

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

01 Body

emailstringRequired
The contact's email address. Unique within the project.
firstNamestringOptional
Given name.
lastNamestringOptional
Family name.
subscribedbooleanOptional
Whether the contact is opted in. Defaults to true. When false, unsubscribedAt is stamped on create.
metadataobjectOptional
Free-form key/value pairs stored alongside the contact.
Subscription is not suppressionThe 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.

02 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" }
  }'

03 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"
}