Newsletter Subscriptions

Overview

SentinMail lets you manage your newsletter subscribers programmatically — create subscribers, organize them into lists, and target them with segments. This guide covers the API endpoints you'll use most as an integrator.

Add a Subscriber

Code

bash

1curl -X POST "https://api.sentinmail.app/api/emails/subscribers/" \
2  -H "X-API-Key: YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "email": "newuser@example.com",
6    "first_name": "Jane",
7    "last_name": "Doe"
8  }'

Response (201):

Code

json

1{
2  "id": "sub-uuid-here",
3  "email": "newuser@example.com",
4  "first_name": "Jane",
5  "last_name": "Doe",
6  "created_at": "2026-04-02T12:00:00Z"
7}

List All Subscribers

Code

bash

1curl -X GET "https://api.sentinmail.app/api/emails/subscribers/" \
2  -H "X-API-Key: YOUR_API_KEY"

Filter and search:

Code

bash

1# Search by name or email
2?search=jane
3 
4# Sort by creation date (newest first)
5?ordering=-created_at
6 
7# Paginate
8?page=2

Bulk Add Subscribers (CSV)

Upload a CSV file to add subscribers in bulk:

Code

bash

1curl -X POST "https://api.sentinmail.app/api/emails/subscribers/bulk/" \
2  -H "X-API-Key: YOUR_API_KEY" \
3  -F "file=@subscribers.csv"

CSV format:

Code

csv

1email,first_name,last_name
2jane@example.com,Jane,Doe
3john@example.com,John,Smith

Manage Subscriber Lists

Create a List

Code

bash

1curl -X POST "https://api.sentinmail.app/api/emails/lists/" \
2  -H "X-API-Key: YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "name": "Weekly Newsletter",
6    "description": "Subscribers to the weekly product update"
7  }'

List All Lists

Code

bash

1curl -X GET "https://api.sentinmail.app/api/emails/lists/" \
2  -H "X-API-Key: YOUR_API_KEY"

Add Subscribers to a List

Put the list on the subscriber when you create it, with lists:

Code

bash

1curl -X POST "https://api.sentinmail.app/api/emails/subscribers/" \
2  -H "X-API-Key: YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "email": "newuser@example.com",
6    "lists": ["LIST_ID"]
7  }'

For a subscriber that already exists, update its lists. This replaces the subscriber's lists, so include the ones it is already on:

Code

bash

1curl -X PATCH "https://api.sentinmail.app/api/emails/subscribers/SUB_ID/" \
2  -H "X-API-Key: YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{ "lists": ["EXISTING_LIST_ID", "LIST_ID"] }'

Creating an email that is already a subscriber returns 400. Find it with GET /api/emails/subscribers/?search=EMAIL, then update its lists as above.

Lists must belong to the same company as the API key. An API key always works on its own company, so you never need to send company.

Note

Changing lists for many subscribers at once (`POST /api/emails/subscribers/bulk-update-lists/`) is for company admins and owners signed in to SentinMail. It is not available with an API key.

Remove a Subscriber

Delete

Permanently remove a subscriber:

Code

bash

1curl -X DELETE "https://api.sentinmail.app/api/emails/subscribers/SUB_ID/" \
2  -H "X-API-Key: YOUR_API_KEY"

Suppress (Recommended)

Instead of deleting, add them to the suppression list to prevent future emails while keeping their data:

Code

bash

1curl -X POST "https://api.sentinmail.app/api/emails/suppressions/" \
2  -H "X-API-Key: YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "email": "unsubscribed@example.com",
6    "reason": "User requested opt-out"
7  }'

Tip

Suppression is usually better than deletion for compliance — it keeps a record of the opt-out and prevents accidentally re-adding the address.

Segments

Create dynamic groups of subscribers based on rules:

Code

bash

1curl -X POST "https://api.sentinmail.app/api/emails/segments/" \
2  -H "X-API-Key: YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "name": "Engaged Users",
6    "description": "Subscribers who opened an email in the last 30 days",
7    "rules": {
8      "conditions": [
9        {
10          "field": "last_opened",
11          "operator": "within_days",
12          "value": 30
13        }
14      ],
15      "match": "all"
16    }
17  }'

Segments are dynamic — subscribers automatically enter or exit the segment as their data changes.

Pagination

All list endpoints return paginated results:

Code

json

1{
2  "count": 2500,
3  "next": "https://api.sentinmail.app/api/emails/subscribers/?page=2",
4  "previous": null,
5  "results": [...]
6}

Default page size is 20 items. Navigate with the ?page= parameter.

Documentation

Newsletter Subscriptions

Overview

Add a Subscriber

List All Subscribers

Bulk Add Subscribers (CSV)

Manage Subscriber Lists

Create a List

List All Lists

Add Subscribers to a List

Remove a Subscriber

Delete

Suppress (Recommended)

Segments

Pagination