mailer123
API reference

Groups

Create, read, update, and delete contact groups.

Organize your audience: create groups, manage their members, and use them as campaign audiences.

List groups

GET/v1/groupsfull access

Returns every group in the project with its member ids and count, newest first.

bash
curl https://mailer123.com/api/v1/groups \
-H "Authorization: Bearer m123_your_api_key"
json
{ "data": [ { "id": "...", "name": "Beta testers", "contactIds": ["..."], "contactCount": 1 } ] }

Create a group

POST/v1/groupsfull access

Members come from contact ids and/or emails (matched to existing contacts). At least one source must resolve to a contact — empty groups aren't allowed.

FieldTypeRequiredDescription
namestringrequiredGroup name. Must be unique within the project.
contact_idsstring[]optionalMember contact ids.
emailsstring[]optionalMember emails, matched to existing contacts.
bash
curl -X POST https://mailer123.com/api/v1/groups \
-H "Authorization: Bearer m123_your_api_key" \
-H "Content-Type: application/json" \
-d '{ "name": "Beta testers", "emails": ["ada@example.com"] }'
json
HTTP/1.1 201 Created

{ "data": { "id": "...", "name": "Beta testers", "contactIds": ["..."], "contactCount": 1 } }

Retrieve a group

GET/v1/groups/{id}full access

Returns one group by id with its resolved members, or 404 not_found. memberCount is the number of member ids stored on the group; contacts lists the members that still exist.

json
{ "data": { "id": "...", "name": "Beta testers", "memberCount": 1, "contacts": [ { "id": "...", "email": "ada@example.com", "name": "Ada Lovelace" } ] } }

Update a group

PATCH/v1/groups/{id}full access

Partial update — send only the fields you want to change. contact_ids replaces the entire member list; omit it to leave membership untouched. A group must always keep at least one member.

FieldTypeDescription
namestringNew group name (deduped against your other groups).
contact_idsstring[]New full member list, replacing the existing members.
bash
curl -X PATCH https://mailer123.com/api/v1/groups/GROUP_ID \
-H "Authorization: Bearer m123_your_api_key" \
-H "Content-Type: application/json" \
-d '{ "name": "Beta testers (2026)" }'

Add contacts to a group

POST/v1/groups/{id}/contactsfull access

Add members incrementally without replacing the existing list. Accepts contact ids and/or emails; contacts already in the group are not duplicated. matched is how many of the supplied contacts resolved to existing ones.

FieldTypeDescription
contact_idsstring[]Contact ids to add.
emailsstring[]Emails to add, matched to existing contacts.
bash
curl -X POST https://mailer123.com/api/v1/groups/GROUP_ID/contacts \
-H "Authorization: Bearer m123_your_api_key" \
-H "Content-Type: application/json" \
-d '{ "emails": ["grace@example.com"] }'
json
{ "data": { "id": "...", "name": "Beta testers", "memberCount": 2, "contacts": [ ... ] }, "matched": 1 }

Delete a group

DELETE/v1/groups/{id}full access

Permanently delete a group. The contacts themselves are not deleted, only the grouping. Returns { "deleted": true }.

Errors

insufficient_scope (403 — sending-only key), validation_error (400 — no members resolved or empty update), conflict (409 — duplicate group name), not_found (404). See the error reference.

PreviousContactsNextCampaigns