Contacts

Contacts are the subscribers in your marketing audience. Every contact belongs to your account, carries a consent record, and has a lifecycle status. Contacts can be grouped into Lists and targeted with Segments.

All endpoints require an Authorization: Bearer YOUR_API_KEY header.

The contact object

{
  "id": "ct_abc123",
  "email": "jane@example.com",
  "email_normalized": "jane@example.com",
  "first_name": "Jane",
  "last_name": "Doe",
  "attributes": { "plan": "pro" },
  "status": "subscribed",
  "eligibility": "eligible",
  "eligibility_reason": null,
  "consent_source": "api",
  "consent_at": "2026-01-15T10:30:00Z",
  "unsubscribed_at": null,
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-01-15T10:30:00Z"
}

List contacts

GET /v1/contacts

Returns a paginated page of contacts.

Query parameters

Response

{
  "contacts": [ /* contact objects */ ],
  "total": 1280,
  "page": 1,
  "totalPages": 26
}

curl "https://api.envloped.com/v1/contacts?status=subscribed&limit=50" \
  -H "Authorization: Bearer en_abc123..."

Create a contact

POST /v1/contacts

Creates a single contact and, optionally, adds it to lists. This is a strict create — a contact with the same normalized email already existing returns 409.

Request body

Consent is stamped at creation time (consent_at = now()), and the caller IP is recorded on the consent record. Contacts created through this API always have consent_source: "api" — it reflects the channel consent came through, so it is set automatically and cannot be overridden in the request.

Response — 201 Created

{
  "contact": { /* contact object */ },
  "added_to_lists": ["ls_newsletter"],
  "invalid_lists": []
}

curl -X POST https://api.envloped.com/v1/contacts \
  -H "Authorization: Bearer en_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "first_name": "Jane",
    "attributes": { "plan": "pro" },
    "list_ids": ["ls_newsletter"]
  }'

Errors

Create or update contacts in bulk

POST /v1/contacts/batch

Upsert up to 1000 contacts per request, keyed on the normalized email. This is the endpoint to sync an approvals table or a members table from your own backend — no CSV, no nightly job.

Request body

Each entry in contacts:

Response — always 200

Partial success is the contract. The request only fails as a whole if it is malformed.

{
  "processed": 1000,
  "created": 812,
  "updated": 176,
  "rejected_ineligible": 11,
  "invalid": 1,
  "results": [
    { "email": "jane@example.com", "result": "created", "id": "ct_abc123" },
    { "email": "rejected@example.com", "result": "rejected_ineligible" },
    { "email": "typo@example.com", "result": "invalid",
      "reason": "invalid_attributes", "unknown_fields": ["citty"] }
  ]
}

curl -X POST https://api.envloped.com/v1/contacts/batch \
  -H "Authorization: Bearer en_abc123..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: members-backfill-batch-17" \
  -d '{
    "attributes_mode": "merge",
    "contacts": [{
      "email": "jane@example.com",
      "member_status": "approved",
      "first_name": "Jane",
      "attributes": { "city": "Singapore", "date_of_birth": "1996-04-12" },
      "list_ids": ["ls_members"]
    }]
  }'

Send an Idempotency-Key and a replay returns the original receipt verbatim rather than re-running — which is what makes a 35-request backfill reconcilable if one response goes missing.

Two behaviours worth knowing:

• Never resurrect. An existing unsubscribed contact stays unsubscribed even if the sync says approved. An unsubscribe is the contact's decision, not your system's.
• Contacts and list membership commit together. The receipt certifies a committed state, so it cannot report a contact that landed without its lists.

Eligibility

Eligibility is a separate gate from subscription status and from deliverability suppression. It answers is this person allowed to be mailed at all — the case where your own system says someone is not a member, was rejected, or was removed.

• A batch row whose member_status is not approved never creates a contact and comes back rejected_ineligible with HTTP 200 — so you can fire your entire members table at this endpoint without branching.
• An existing contact that flips from approved to rejected, pending or removed is set to eligibility: "ineligible" and suppressed. It is not deleted: deleting loses the memory of why they must not be mailed.
• At send time, an ineligible contact is recorded as skipped with the reason ineligible and is never mailed. No segment, list, or campaign can override this.

Re-approving a contact restores eligibility but does not lift the suppression that was written on downgrade — clear it deliberately if that is what you want.

Polling for changes

To mirror unsubscribes back into your own database, poll with since:

curl "https://api.envloped.com/v1/contacts?status=unsubscribed&since=2026-08-09T00:00:00Z" \
  -H "Authorization: Bearer en_abc123..."

{
  "contacts": [ /* contact objects */ ],
  "next_cursor": "eyJ1IjoiMjAyNi0wOC0wOVQxMDozMDowMFoiLCJpIjoiY3RfYWJjIn0"
}

Follow next_cursor until it comes back null; since only needs to be sent on the first request. This is a keyset poll over (updated_at, id), not offset paging — under an active writer, offset paging silently skips rows, which for an unsubscribe feed means missing an opt-out.

Retrieve a contact

GET /v1/contacts/:id

Returns the contact plus its live list memberships.

{
  "contact": { /* contact object */ },
  "lists": [
    { "id": "ls_newsletter", "name": "Newsletter", "unsubscribed_at": null }
  ]
}

Returns 404 with { "error": "Contact not found" } if the id is unknown.

Update a contact

PATCH /v1/contacts/:id

Updates mutable fields. Only supplied fields change. Setting status to unsubscribed stamps unsubscribed_at; moving to subscribed/pending clears it.

Request body

An attribute that fails validation returns 422 naming the offending keys.

curl -X PATCH https://api.envloped.com/v1/contacts/ct_abc123 \
  -H "Authorization: Bearer en_abc123..." \
  -H "Content-Type: application/json" \
  -d '{ "status": "unsubscribed" }'

Response: { "contact": { /* updated contact */ } }.

Delete a contact (GDPR erasure)

DELETE /v1/contacts/:id

Hard delete. The contact row is removed permanently and its list memberships are cascaded away. Campaign history is preserved with the contact reference nulled, so aggregate reports stay intact while the PII is gone. This is the endpoint to satisfy a right-to-erasure request.

{ "deleted": true, "id": "ct_abc123" }

Export contacts

GET /v1/contacts/export

Streams the full contact list as a CSV file (Content-Type: text/csv) with the columns email, first_name, last_name, status, consent_source, consent_at, unsubscribed_at, created_at. The export is keyset-paginated server-side so it stays memory-flat for very large audiences.

curl "https://api.envloped.com/v1/contacts/export" \
  -H "Authorization: Bearer en_abc123..." \
  -o contacts.csv

SDKs & CLI

The same operations are available in the official SDKs and CLI:

// JavaScript / TypeScript
await client.contacts.create({ email: 'jane@example.com', list_ids: ['ls_newsletter'] });
const { contacts } = await client.contacts.list({ status: 'subscribed' });

// Go
client.Contacts.Create(&envloped.CreateContactRequest{Email: "jane@example.com"})

# CLI
envloped contacts create jane@example.com --list ls_newsletter
envloped contacts list --status subscribed