EmailOctopus logo

API > Lists > Update Multiple Contacts of List

PUT https://emailoctopus.com/api/1.6/lists/:listId/contacts

Update multiple contacts of a list, up to a maximum of 100 per request.

Route parameters
listId (string) The ID of the list.
Parameters
api_key (string) Your API key.
data (array of structs, max. 100)

Details of each contact:

id (string) The ID of the list contact, or an MD5 hash of the lowercase version of the list contact's email address.
email_address (string, optional) The new email address for the contact.
fields (object, optional) An object containing key/value pairs of field values, using the field's tag as the key. Fields not referenced in the object will not be updated.
tags (object, optional) An object containing key/value pairs, where the key is the tag name and the value is true to add the tag or false to remove it. Tags that are not referenced in the object will not be updated. Only tags that already exist for this list can be added or removed.
status (string, optional) The new status of the contact: SUBSCRIBED, UNSUBSCRIBED or PENDING.
200 (success) returns
data (array of structs)

Details of updated contacts:

id (string) The identifier of the contact.
email_address (string) The email address of the contact.
fields (object) An object containing key/value pairs of field values, using the field's tag as the key.
tags (array) An array of tags associated with the contact.
status (string) The status of the contact: SUBSCRIBED, UNSUBSCRIBED or PENDING.
created_at (string) When the contact was created, in ISO 8601 format.
last_updated_at (string) When the contact was last updated, in ISO 8601 format.

Details of contact updates with errors:

id (string) The identifier of the contact that had an error.
status (string)
Item-specific status codes
MEMBER_NOT_FOUND The contact could not be found.
INVALID_LIST_TAG A tag to be added to the contact does not exist.
Non-200 (error) returns

Details of the error:

code (string) The error code.
message (string) A description of the error.
Method-specific error codes
NOT_FOUND The list could not be found.
API-wide error codes
INVALID_PARAMETERS Parameters are missing or invalid.
API_KEY_INVALID Your API key is invalid.
UNAUTHORISED You're not authorised to perform that action.
NOT_FOUND The requested endpoint does not exist.
UNKNOWN An unknown error has occurred.
Example request
                        
                            {
    "api_key": "00000000-0000-0000-0000-000000000000",
    "data": [
        {
            "id": "f9087de8-9301-475e-8e2f-2808d7275e86",
            "email_address": "alex@example.com",
            "fields": {
                "FirstName": "Alex",
                "LastName": "A",
                "Birthday": "1990-01-01"
            },
            "tags": {
                "vip": true,
                "tagToRemove": false
            },
            "status": "SUBSCRIBED"
        },
        {
            "id": "977c401679d72fa50c5a2fae368d5ad5",
            "email_address": "charlie@example.com",
            "fields": {
                "FirstName": "Charlie",
                "LastName": "B",
                "Birthday": "1995-01-01"
            },
            "status": "SUBSCRIBED"
        },
        {
            "id": "6144ff83ab0d757abdf4bf849b0c25b1",
            "email_address": "dana@example.com",
            "fields": {
                "FirstName": "Dana",
                "LastName": "C",
                "Birthday": "2000-01-01"
            },
            "status": "SUBSCRIBED"
        }
    ]
}

                        
                    
Example response
                        
                            {
    "data": [
        {
            "id": "f9087de8-9301-475e-8e2f-2808d7275e86",
            "email_address": "alex@example.com",
            "fields": {
                "FirstName": "Alex",
                "LastName": "A",
                "Birthday": "1990-01-01"
            },
            "tags": ["vip"],
            "status": "SUBSCRIBED",
            "created_at": "2024-12-13T00:00:00+00:00",
            "last_updated_at": "2024-12-14T02:53:08+00:00"
        },
        {
            "id": "10dbe5ee-21d4-4d4d-aa46-908775d791c7",
            "email_address": "charlie@example.com",
            "fields": {
                "FirstName": "Charlie",
                "LastName": "B",
                "Birthday": "2000-01-01"
            },
            "tags": ["vip"],
            "status": "SUBSCRIBED",
            "created_at": "2024-12-14T02:53:08+00:00",
            "last_updated_at": "2024-12-13T00:00:00+00:00"
        },
        {
            "id": "6144ff83ab0d757abdf4bf849b0c25b1",
            "status": "MEMBER_NOT_FOUND"
        }
    ]
}

                        
                    
Code sample
copy