Maillayer/Docs

Contacts

API reference for creating, updating and deleting contacts, with lists, properties, sign-up IP and location.

Using an AI agent? Just ask:“Add [email protected] to my Customers list.”Connect your agent →

Create or update a contact#

POST/api/v1/contacts

Creates the contact, or updates the one with the same email. Never re-subscribes someone who unsubscribed.

Body

  • emailstringrequired
    The contact's address.
  • first_namestring | null
    First name.
  • last_namestring | null
    Last name.
  • propertiesobject
    Custom fields (string, number, boolean or null), merged with existing ones. Usable in emails as variables.
  • listsstring[]
    Up to 20 list names or ids. Missing lists are created.
  • ipstring | null
    The sign-up IP. Turns on the IP contact checks and fills in location.
  • countrystring | null
    Two-letter country code like US. Overrides what IPs say.
  • timezonestring | null
    IANA timezone like America/New_York. Overrides what IPs say.
Request
curl https://agent.maillayer.com/api/v1/contacts \
  -H "Authorization: Bearer $MAILLAYER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "first_name": "Ada",
    "properties": { "plan": "Pro" },
    "lists": ["Customers"],
    "ip": "203.0.113.7"
  }'
Response · 200
{
  "id": "0b4f…",
  "email": "[email protected]",
  "first_name": "Ada",
  "last_name": null,
  "properties": { "plan": "Pro" },
  "status": "subscribed",
  "lists": ["Customers"],
  "location": null,
  "check": { "status": "pending", "reason": null, "description": null }
}

location is { country, region, city, timezone, source } once known; a sign-up IP is looked up right after the response. check becomes passed or flagged within seconds.

Delete a contact#

DELETE/api/v1/contacts/:email

Removes the contact and its list memberships (for example for a GDPR request). Bounces and spam complaints stay suppressed so they can't be emailed by mistake.

Request
curl -X DELETE https://agent.maillayer.com/api/v1/contacts/ada%40example.com \
  -H "Authorization: Bearer $MAILLAYER_KEY"
Response · 200
{ "deleted": true }