Upsert Contact

Creates a new contact or updates an existing contact if the email already exists. This is the recommended endpoint for most contact synchronization scenarios.

POST /contacts/email

cURL

curl --request POST \
  --url https://api.autosend.com/v1/contacts/email \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "email": "[e-mail]",
  "firstName": "John",
  "lastName": "Doe",
  "userId": "user_12345",
  "customFields": {
    "company": "Acme Corp",
    "role": "Developer",
    "plan": "premium"
  }
}'

Response

{
  "success": true,
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "email": "[e-mail]",
    "firstName": "John",
    "lastName": "Doe",
    "userId": "user_12345",
    "customFields": {
      "company": "Acme Corp",
      "role": "Developer",
      "plan": "premium"
    },
    "updatedAt": "2024-01-15T10:30:00.000Z",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "projectId": "229f1f77bcf86cd9273048038"
  }
}

cURL

curl --request POST \
  --url https://api.autosend.com/v1/contacts/email \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "email": "[e-mail]",
  "firstName": "John",
  "lastName": "Doe",
  "userId": "user_12345",
  "customFields": {
    "company": "Acme Corp",
    "role": "Developer",
    "plan": "premium"
  }
}'

Response

{
  "success": true,
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "email": "[e-mail]",
    "firstName": "John",
    "lastName": "Doe",
    "userId": "user_12345",
    "customFields": {
      "company": "Acme Corp",
      "role": "Developer",
      "plan": "premium"
    },
    "updatedAt": "2024-01-15T10:30:00.000Z",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "projectId": "229f1f77bcf86cd9273048038"
  }
}

---

Authorizations

Authorizations · string | header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

Contact information to create or update

email · string<email> · required

Valid email address (automatically normalized to lowercase)

Example: "[e-mail]"

firstName · string

Contact’s first name

Example: "John"

lastName · string

Contact’s last name

Example: "Doe"

userId · string

Your application’s user identifier

Example: "user_12345"

customFields · object

Key-value pairs for custom contact attributes

Show child attributes

customFields.{key} · string

Example:

{
  "company": "Acme Corp",
  "role": "Developer",
  "plan": "premium"
}

listIds · array

IDs of contact lists - Separate from global contacts. Do not pass segment IDs. This will run Segmentations and Automations for the newly passed contact list ids.

Example: ["507f1f77bcf86cd799439011"]

Response

Contact created or updated successfully

success · boolean

Indicates if the request was successful

Example: true

data · object

Show child attributes

data.id · string

Contact ID

Example: "507f1f77bcf86cd799439011"

data.email · string

Contact email address

Example: "[e-mail]"

data.firstName · string

Contact’s first name

Example: "John"

data.lastName · string

Contact’s last name

Example: "Doe"

data.userId · string

Your application’s user identifier

Example: "user_12345"

data.customFields · object

Custom contact attributes

Show child attributes

customFields.{key} · string

Example:

{
  "company": "Acme Corp",
  "role": "Developer",
  "plan": "premium"
}

data.createdAt · string

Contact creation timestamp

Example: "2024-01-15T10:30:00.000Z"

data.updatedAt · string

Contact last update timestamp

Example: "2024-01-15T10:30:00.000Z"

data.projectId · string

Project ID that the contact belongs to

Example: "229f1f77bcf86cd9273048038"

data.listIds · array

Contact List IDs

Example: ["507f1f77bcf86cd799439011"]