Marketing Platform

Manage your contacts in Brevo

Learn how to create and update contacts using the Brevo API

Import contacts to Brevo to send email campaigns, SMS, and marketing automation messages. Use the API to create and update contacts programmatically.

Import at least the contact’s email address. You can also import additional contact attributes such as first name, last name, birthday, mobile phone number, and other custom fields.

Other methods to manage contacts

To manage contacts through the Brevo app or import contacts using CSV files, see the help center tutorial.

Before you start

1

Get your API key

Retrieve your API key from your account settings. Read the Authentication guide for details.

2

Understand the API

If you’re new to the Marketing API, read the Quickstart guide.

Create a contact

Create contacts using the POST /v3/contacts endpoint. You can create email contacts, SMS contacts, or both.

Endpoint

POST
/v3/contacts
1curl -X POST https://api.brevo.com/v3/contacts \
2     -H "api-key: <apiKey>" \
3     -H "Content-Type: application/json" \
4     -d '{}'

Request parameters

Create different types of contacts:

Request

attributesmap from strings to doubles or strings or booleans or lists of stringsOptional
Pass the set of attributes and their values. The attribute's parameter should be passed in capital letter while creating a contact. Values that don't match the attribute type (e.g. text or string in a date attribute) will be ignored. **These attributes must be present in your Brevo account**. For eg: **{"FNAME":"Elly", "LNAME":"Roger", "COUNTRIES": ["India","China"]}**
emailstringOptionalformat: "email"
Email address of the user. **Mandatory if "ext_id" & "SMS" field is not passed.**
emailBlacklistedbooleanOptional
Set this field to blacklist the contact for emails (emailBlacklisted = true)
ext_idstringOptional
Pass your own Id to create a contact.
listIdslist of longsOptional
Ids of the lists to add the contact to
smsBlacklistedbooleanOptional
Set this field to blacklist the contact for SMS (smsBlacklisted = true)
smtpBlacklistSenderlist of stringsOptional
transactional email forbidden sender for contact. Use only for email Contact ( only available if updateEnabled = true )
updateEnabledbooleanOptionalDefaults to false
Facilitate to update the existing contact in the same request (updateEnabled = true)

Email contact:

1{
2  "email": "thomas.bianchi@example.com"
3}

SMS contact:

1{
2  "attributes": {
3    "SMS": "0612345678"
4  }
5}

Email and SMS contact with attributes:

1{
2  "email": "thomas.bianchi@example.com",
3  "attributes": {
4    "SMS": "0612345678",
5    "LASTNAME": "Bianchi",
6    "FIRSTNAME": "Thomas",
7    "DELIVERYADDRESS": "176 Boulevard des fleurs, 75014 Paris, France"
8  }
9}

Assign to contact lists:

1{
2  "email": "thomas.bianchi@example.com",
3  "listIds": [1, 5]
4}

Get contact list IDs from Contacts > Lists in the Brevo platform or using the get all lists endpoint.

Request example

1curl --request POST \
2  --url https://api.brevo.com/v3/contacts \
3  --header 'accept: application/json' \
4  --header 'api-key: YOUR_API_KEY' \
5  --header 'content-type: application/json' \
6  --data '{
7    "email": "john.doe@example.com",
8    "attributes": {
9      "SMS": "0611223344",
10      "FNAME": "John",
11      "LNAME": "Doe"
12    },
13    "listIds": [11],
14    "emailBlacklisted": false,
15    "smsBlacklisted": false,
16    "updateEnabled": false
17  }'

Response

A successful response returns status code 201 with the contact ID:

1{
2  "id": 123
3}

If the request fails, you’ll receive a 400 error. Common errors include:

  • Invalid email address or phone number
  • Email or phone number already exists in your database
  • Missing or invalid API key
  • Missing Content-Type: application/json header

Verify the contact

After creating a contact, verify it was created:

  1. Check the Contacts section in the Brevo platform
  2. Use the retrieve contact information endpoint
API Reference testing

You can test the endpoint using the API Reference. When testing, you make real API calls that count against your rate limits and credits.

Code examples

$curl --request POST \
>  --url https://api.brevo.com/v3/contacts \
>  --header 'api-key:YOUR_API_KEY' \
>  --header 'Content-Type: application/json' \
>  --data '{"email": "testmail@example.com", "attributes": {"SMS": "0611223344", "FNAME": "John", "LNAME": "Doe"}, "listIds": [11], "emailBlacklisted": false, "smsBlacklisted": false, "updateEnabled": false}'

For each request, include the following headers:

  • api-key: YOUR_API_KEY
  • content-type: application/json
  • accept: application/json
Using API clients

For production integrations, use our API clients which provide shortcuts and easier integration. Available clients: C#, Go, Java, Node.js, PHP, Python, Ruby, and TypeScript.

Update a contact

Update existing contacts using the PUT /v3/contacts/{identifier} endpoint.

Endpoint

PUT https://api.brevo.com/v3/contacts/{identifier}

The identifier is the contact’s email address or phone number in the format <phone_number>@mailin-sms.com (e.g., 0612345678@mailin-sms.com).

Request example

1curl --request PUT \
2  --url https://api.brevo.com/v3/contacts/testmail@example.com \
3  --header 'api-key:YOUR_API_KEY' \
4  --header 'content-type: application/json' \
5  --data '{
6    "attributes": {
7      "FNAME": "Alex",
8      "LNAME": "Roger"
9    }
10  }'

Response

A successful update returns status code 204 with no response body.

Code examples

$curl --request PUT \
>  --url https://api.brevo.com/v3/contacts/testmail@example.com \
>  --header 'api-key:YOUR_API_KEY' \
>  --header 'content-type: application/json' \
>  --data '{"attributes": {"FNAME": "Alex", "LNAME": "Roger"}}'

Manage contact lists

Assign contacts to lists:

1{
2  "listIds": [1, 5]
3}

Unassign contacts from lists:

1{
2  "unlinkListIds": [1]
3}

Common use cases

Create a contact with email and attributes

1{
2  "email": "customer@example.com",
3  "attributes": {
4    "FNAME": "Jane",
5    "LNAME": "Smith",
6    "BIRTHDATE": "1990-01-15",
7    "CITY": "Paris"
8  },
9  "listIds": [1]
10}

Update contact attributes

1{
2  "attributes": {
3    "CITY": "London",
4    "COUNTRY": "UK"
5  }
6}

Add contact to multiple lists

1{
2  "listIds": [1, 2, 3]
3}

Troubleshooting

Error: Invalid email address

Problem: Request fails with email validation error.

Solution: Verify the email address format is correct (e.g., user@example.com).

Error: Contact already exists

Problem: Request fails because contact already exists.

Solution: Set updateEnabled: true in the create request to update existing contacts, or use the update endpoint instead.

Error: Missing API key

Problem: Request fails with authentication error.

Solution: Ensure the api-key header is included in your request with a valid API key.

Next steps