mailer123
API reference

Contacts

Create, read, update, and delete contacts.

Manage your audience: create, read, update, and delete contacts and their custom fields.

List contacts

GET/v1/contactsfull access

Returns every contact in the project, with email, name, source, segments, suppression status, and custom fields.

bash
curl https://mailer123.com/api/v1/contacts \
-H "Authorization: Bearer m123_your_api_key"
json
{ "data": [ { "id": "...", "email": "ada@example.com", "name": "Ada Lovelace" } ] }

Create a contact

POST/v1/contactsfull access

The address is validated and checked against your suppression list. If the contact already exists, you get it back with 200 instead of 201.

FieldTypeRequiredDescription
emailstringrequiredContact email address.
namestringoptionalDisplay name. Defaults to the address's local part.
custom_fieldsobjectoptionalCustom field values keyed by field key, coerced against your schema.
bash
curl -X POST https://mailer123.com/api/v1/contacts \
-H "Authorization: Bearer m123_your_api_key" \
-H "Content-Type: application/json" \
-d '{ "email": "ada@example.com", "name": "Ada Lovelace", "custom_fields": { "company": "Analytical Engines" } }'
json
HTTP/1.1 201 Created

{ "data": { "id": "...", "email": "ada@example.com", "name": "Ada Lovelace", "customFields": { "company": "Analytical Engines" } } }

Retrieve a contact

GET/v1/contacts/{id}full access

Returns one contact by id, or 404 not_found if it doesn't exist in this project.

Update a contact

PATCH/v1/contacts/{id}full access

Partial update — send only the fields you want to change.

FieldTypeDescription
namestringNew display name.
emailstringNew email address (deduped against your other contacts).
custom_fieldsobjectReplaces the contact's custom field values.
subscribedbooleanfalse adds an unsubscribe suppression for the address; true clears it.
bash
curl -X PATCH https://mailer123.com/api/v1/contacts/CONTACT_ID \
-H "Authorization: Bearer m123_your_api_key" \
-H "Content-Type: application/json" \
-d '{ "name": "Ada, Countess of Lovelace", "subscribed": true }'

Delete a contact

DELETE/v1/contacts/{id}full access

Permanently delete a contact. Returns { "deleted": true }.

Errors

insufficient_scope (403 — sending-only key), validation_error (400), conflict (409 — suppressed or duplicate email), not_found (404). See the error reference.

PreviousEmailsNextGroups