Skip to content

Create a contact

Request

Create a new contact in your account. You can include tags, custom properties, and all contact fields.

Backward compatibility: Contacts are still created as subscribed immediately unless you explicitly pass double_opt_in: true. Existing integrations using status: "subscribed" continue to behave as single opt-in.

Double opt-in: Pass double_opt_in: true to create the contact as pending_confirmation, send a confirmation email, and move the contact to subscribed only after the subscriber confirms. Pending contacts are excluded from marketing segment sends until confirmed.

Fields:

  • Email (required) - unique per customer
  • Name fields - first_name/last_name or combined name
  • Contact info - phone, city, country
  • Custom properties - unlimited flexible fields
  • Tags - categorize your contacts

Note: Email must be unique. Returns 409 if email already exists.

Security
ApiKeyAuth
Bodyapplication/jsonrequired
emailstring, (email)required

Contact email address (unique per customer)

Example:"john@example.com"
namestring

Full name (optional if first_name and last_name provided)

Example:"John Doe"
first_namestring

First name

Example:"John"
last_namestring

Last name

Example:"Doe"
phonestring

Phone number

Example:"+1234567890"
citystring

City

Example:"San Francisco"
countrystring

Country

Example:"USA"
statusstring

Contact subscription status. Prefer double_opt_in: true instead of setting pending_confirmation directly.

Default:"subscribed"
Enum:"subscribed""pending_confirmation""unsubscribed""bounced""complained"
double_opt_inboolean

When true, creates the contact as pending_confirmation, sends a confirmation email, and changes status to subscribed only after the subscriber confirms.

Default:false
consentobject

Optional consent/audit metadata stored with the confirmation request.

confirmationobject

Optional confirmation email settings. Used only when double_opt_in: true.

custom_fieldsobject

Legacy custom fields (prefer custom_properties)

Example:
{
  "legacy_field": "value"
}
custom_propertiesobject

User-defined custom properties (flexible JSONB storage)

Example:
{
  "company": "Acme Inc",
  "role": "Manager",
  "plan": "premium"
}
tagsArray of strings

Array of tags to assign

Example:
[
  "premium",
  "early-adopter"
]
sourcestring

The source/origin of this contact:

  • api: Created via API (default)
  • import: Bulk CSV import
  • form: Web form submission
  • manual: Manually created via dashboard
Default:"api"
Enum:"api""import""form""manual"
Example:"api"
curl -i -X POST \
  https://api.mailerlogic.net/api/v1/contacts \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "email": "john@example.com",
    "first_name": "John",
    "last_name": "Doe"
  }'

Responses

Contact created successfully

Bodyapplication/json
successboolean
Example:true
dataobject
Response
{
  "success": true,
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "jane@example.com",
    "created_at": "2019-08-24T14:15:22Z",
    "double_opt_in": { … }
  }
}