---
title: "Create a contact"
method: POST
path: "/audience/contacts"
tags: ["Audience"]
---

# Create a contact

`POST /audience/contacts`

## Request

- Base URL: `https://app.lettr.com/api`
- URL: `https://app.lettr.com/api/audience/contacts`
- Auth: HTTP bearer

Create a single contact. If `double_opt_in` is provided the contact is created in `unverified` status and receives a confirmation email — they become `subscribed` only after clicking the confirmation link. Requires the `audience:write` scope and is blocked for sandbox API keys.

## Request body

- StoreAudienceContactRequest: Request to create a single contact
  - `email` string, email, required
  - `list_id` string, uuid, nullable: Optional list to add the contact to. Must be a list of your team, otherwise the response is `422` with `errors.list_id`.
  - `properties` object, nullable: Custom property values. Each key must match a property defined for the team.
  - `double_opt_in` DoubleOptInConfig: Double opt-in configuration. When provided, the contact receives a confirmation email and is created in `unverified` status until they click the confirmation link.
    - `from` string, email, required
    - `from_name` string, nullable
    - `subject` string, required
    - `template_slug` string, required
    - `redirect_url` string, uri, required

## Response `201`

Contact created

- ShowAudienceContactResponse
  - `message` string, required
  - `data` AudienceContactView, required: Audience contact
    - `id` string, uuid, required
    - `email` string, email, required
    - `status` 'subscribed' | 'unsubscribed' | 'bounced' | 'complained' | 'unverified', required: Contact subscription status
    - `properties` object, required: Custom properties for the contact (string values)
    - `created_at` string, date-time, required
    - `paused_until` string, date-time, nullable, required: End of the contact's send pause, set from the unsubscribe page. While this is in the future the contact keeps status subscribed but campaigns are not delivered to them.
    - `lists` AudienceContactListLink[], required
      - `id` string, uuid, required
      - `name` string, required
    - `topics` AudienceContactTopicLink[], required
      - `id` string, uuid, required
      - `name` string, required

## Other responses

- `401`: Unauthorized - Missing or invalid API key
- `403`: Forbidden - API key does not have the required scope
- `404`: Double opt-in confirmation template not found. Returned only when `double_opt_in` is supplied and its `template_slug` does not exist, has no active (published) version, or no default project is configured for the team. No contact is created.
- `409`: A contact with this email already exists for the team. No contact is created and the existing one is left untouched — update it with `PATCH /audience/contacts/{contactId}`, or use `POST /audience/contacts/bulk` with `update_existing` enabled.
- `422`: Validation error
- `500`: Internal server error
- `502`: Confirmation email transmission failed (upstream provider error). Returned only when `double_opt_in` is supplied and the confirmation email could not be sent.
- `503`: Service unavailable - the API key could not be verified, so the request was not processed. This does not mean the key is invalid; retry after the delay given in the Retry-After header.

---

[API](https://skmtc.dev/lettr/apis/lettr-api.md) · [All operations](https://skmtc.dev/lettr/apis/lettr-api/llms.txt) · [OpenAPI document](https://skmtc.dev/lettr/apis/lettr-api/revisions/48ef0dac1ebd?raw)