Contacts
Subscribers of your newsletters: add, import with cleaning, export, unsubscribe.
- GET /contacts — List contacts
- POST /contacts — Add a contact
- POST /contacts/import — Import contacts
- GET /contacts/export — Export contacts (CSV)
- GET /contacts/{id} — Retrieve a contact
- POST /contacts/{id}/unsubscribe — Unsubscribe
- POST /contacts/{id}/reactivate — Reactivate a dormant contact
- DELETE /contacts/{id} — Delete a contact
get/contacts— List contacts
Keys: full_access
Query parameters
| segment_id | uuid | |
| status | "active" | "pending" | "unsubscribed" | "bounced" | "complained" | "dormant" | |
| search | string | Substring of the email address. |
| limit | integer | 1–100, default 20. |
| after | uuid | Id of the last item of the previous page (older items). |
| before | uuid | Id of the first item of the previous page (newer items). |
curl -X GET https://api.smartletter.ai/contacts \
-H "Authorization: Bearer $SMARTLETTER_API_KEY"Response 200
{
"object": "list",
"has_more": false,
"data": [
{
"object": "contact",
"id": "5b1f2c90-0000-4000-8000-000000000002",
"email": "jane@example.com",
"status": "active",
"segment_id": "2d9e4b11-0000-4000-8000-000000000003"
}
]
}post/contacts— Add a contact
Adds one contact as imported (the same cleaning as an import: invalid syntax, typos, spam traps, role and disposable addresses, suppressions). A refused address answers 422 with the reason. Returns the existing contact when the address is already there.
Keys: full_access · accepts Idempotency-Key
Body
| emailrequired | string | |
| segment_id | uuid | Optional when the workspace has a single active newsletter. |
| name | string | |
| language | string |
curl -X POST https://api.smartletter.ai/contacts \
-H "Authorization: Bearer $SMARTLETTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"email":"jane@example.com","name":"Jane"}'Response 201
{
"object": "contact",
"id": "5b1f2c90-0000-4000-8000-000000000002",
"email": "jane@example.com",
"status": "active",
"existed": false
}post/contacts/import— Import contacts
Up to 1000 rows per call, consent: true required. Rows are cleaned like a CSV import and the answer reports every rejected row with its reason. New accounts' large imports may be held for a quick review.
Keys: full_access · accepts Idempotency-Key
Body
| segment_id | uuid | |
| consentrequired | true | You confirm every contact opted in to receive this newsletter (no bought, rented or scraped list). |
| contactsrequired | object[] |
curl -X POST https://api.smartletter.ai/contacts/import \
-H "Authorization: Bearer $SMARTLETTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"consent":true,"contacts":[{"email":"jane@example.com","name":"Jane","open_rate":0.42}]}'Response 200
{
"object": "import",
"total": 3,
"inserted": 1,
"rejected": 2,
"reasons": {
"invalid": 0,
"typo": 1,
"spam_trap": 0,
"role": 1,
"disposable": 0,
"no_mx": 0,
"duplicate": 0,
"suppressed": 0,
"capped": 0
},
"rejected_rows": [
{
"line": 2,
"email": "bob@gmial.com",
"reason": "typo",
"suggestion": "bob@gmail.com"
},
{
"line": 3,
"email": "info@acme.com",
"reason": "role"
}
],
"pending_review": false
}get/contacts/export— Export contacts (CSV)
Keys: full_access
Query parameters
| segment_id | uuid | |
| status | "active" | "pending" | "unsubscribed" | "bounced" | "complained" | "dormant" |
curl -X GET https://api.smartletter.ai/contacts/export \
-H "Authorization: Bearer $SMARTLETTER_API_KEY"Response 200
email,name,status,segment_id,language,source,subscribed_at,unsubscribed_at
jane@example.com,Jane,active,…get/contacts/{id}— Retrieve a contact
Keys: full_access
curl -X GET https://api.smartletter.ai/contacts/<id> \
-H "Authorization: Bearer $SMARTLETTER_API_KEY"Response 200
{
"object": "contact",
"id": "5b1f2c90-0000-4000-8000-000000000002",
"email": "jane@example.com",
"status": "active",
"engagement": {
"emails_sent": 12,
"emails_opened": 7,
"emails_clicked": 2
}
}post/contacts/{id}/unsubscribe— Unsubscribe
Keys: full_access
curl -X POST https://api.smartletter.ai/contacts/<id>/unsubscribe \
-H "Authorization: Bearer $SMARTLETTER_API_KEY"Response 200
{
"object": "contact",
"id": "5b1f2c90-0000-4000-8000-000000000002",
"status": "unsubscribed"
}post/contacts/{id}/reactivate— Reactivate a dormant contact
Only for contacts put to sleep by the inactive cleanup. An unsubscribed contact can only come back through their own link.
Keys: full_access
curl -X POST https://api.smartletter.ai/contacts/<id>/reactivate \
-H "Authorization: Bearer $SMARTLETTER_API_KEY"Response 200
{
"object": "contact",
"id": "5b1f2c90-0000-4000-8000-000000000002",
"status": "active"
}delete/contacts/{id}— Delete a contact
Keys: full_access
curl -X DELETE https://api.smartletter.ai/contacts/<id> \
-H "Authorization: Bearer $SMARTLETTER_API_KEY"Response 200
{
"object": "contact",
"id": "5b1f2c90-0000-4000-8000-000000000002",
"deleted": true
}