> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zexa.ao/llms.txt
> Use this file to discover all available pages before exploring further.

# Import and Manage Recipient Contacts and Lists in Zexa

> Import, organise, and manage your recipient contacts in Zexa. Create contact lists for campaigns and keep your audience data up to date.

Contacts in Zexa are the people you send messages to. You can add contacts individually, import them in bulk via CSV, or create them programmatically via the API. Contacts are grouped into lists that you target when creating campaigns.

## Add a contact

<Steps>
  <Step title="Open Add Contact">
    In the [Zexa dashboard](https://app.zexa.ao), navigate to **Contacts** > **Add Contact**.
  </Step>

  <Step title="Enter contact details">
    Fill in the contact's **name**, **phone number** (E.164 format, e.g. `+244912345678`), and an optional **email address**.
  </Step>

  <Step title="Assign to a list">
    Select one or more existing contact lists to add this contact to. You can also create a new list from this screen.
  </Step>

  <Step title="Save the contact">
    Click **Save**. The contact is immediately available for use in campaigns.
  </Step>
</Steps>

<Note>
  Phone numbers must be in **E.164 format** (e.g. `+244912345678`). Numbers submitted without a country code will be rejected by the API and the import validator.
</Note>

## Import contacts from CSV

To add many contacts at once, use the bulk CSV import tool.

<Steps>
  <Step title="Download the sample template">
    Go to **Contacts** > **Import** and click **Download Sample CSV** to get the expected column layout.
  </Step>

  <Step title="Prepare your CSV file">
    Fill in your data using the following columns:

    | Column  | Required | Format                       |
    | ------- | -------- | ---------------------------- |
    | `name`  | Yes      | Plain text                   |
    | `phone` | Yes      | E.164 (e.g. `+244912345678`) |
    | `email` | No       | Valid email address          |
  </Step>

  <Step title="Upload the file">
    Return to **Contacts** > **Import**, select your CSV file, and choose the target contact list.
  </Step>

  <Step title="Review and confirm">
    Zexa displays a preview with a count of valid and invalid rows. Fix any errors highlighted in red, then click **Confirm Import**.
  </Step>
</Steps>

## Manage contacts via API

### Create a contact

```bash curl theme={null}
curl --request POST \
  --url https://api.zexa.ao/v1/contacts \
  --header "Authorization: Bearer <api_key>" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Ana Silva",
    "phone": "+244912345678",
    "email": "ana@example.com",
    "lists": ["lst_abc123"]
  }'
```

### List contacts in a list

Use the `list_id`, `page`, and `per_page` query parameters to paginate through a contact list:

```bash curl theme={null}
curl --request GET \
  --url "https://api.zexa.ao/v1/contacts?list_id=lst_abc123&page=1&per_page=50" \
  --header "Authorization: Bearer <api_key>"
```

```json theme={null}
{
  "data": [
    {
      "id": "con_001",
      "name": "Ana Silva",
      "phone": "+244912345678",
      "email": "ana@example.com",
      "opted_out": false,
      "created_at": "2026-06-01T09:00:00Z"
    }
  ],
  "page": 1,
  "per_page": 50,
  "total": 1
}
```

### Delete a contact

```bash curl theme={null}
curl --request DELETE \
  --url https://api.zexa.ao/v1/contacts/con_001 \
  --header "Authorization: Bearer <api_key>"
```

A `204 No Content` response confirms the contact has been removed.

## Contact lists

Contact lists let you group contacts into reusable audiences. A single contact can belong to multiple lists, and a single list can be targeted by multiple campaigns.

To create a list from the dashboard:

<Steps>
  <Step title="Open Lists">
    Go to **Contacts** > **Lists** > **New List**.
  </Step>

  <Step title="Name your list">
    Enter a descriptive name (e.g. **Luanda Subscribers** or **VIP Customers Q3**) and click **Create**.
  </Step>

  <Step title="Add contacts">
    Add contacts to the list manually, via CSV import, or by specifying the list ID when creating contacts through the API.
  </Step>
</Steps>

## Opt-outs and unsubscribes

Zexa automatically manages opt-outs to keep your sending compliant:

* **SMS**: when a recipient replies **STOP** (or a localised equivalent), Zexa marks them as opted out.
* **Email**: when a recipient clicks the unsubscribe link in an email, Zexa marks them as opted out.
* **Opted-out contacts** are automatically excluded from all future campaigns — you do not need to remove them from your lists manually.

You can view opted-out contacts under **Contacts** > **Opt-outs** in the dashboard.

<Tip>
  Always obtain explicit consent before adding contacts to any list. Sending unsolicited messages violates Zexa's Terms of Use and may breach data protection laws applicable in your market.
</Tip>

***

<CardGroup cols={3}>
  <Card title="Campaigns" icon="bullhorn" href="/messaging/campaigns">
    Use your contact lists to launch broadcast campaigns across any channel.
  </Card>

  <Card title="Sender IDs" icon="id-badge" href="/messaging/sender-ids">
    Register the name or number shown to your contacts when they receive messages.
  </Card>

  <Card title="Templates" icon="file-lines" href="/messaging/templates">
    Create WhatsApp templates for proactive outbound messages.
  </Card>
</CardGroup>