Contact properties

Learn how to work with Contact properties with Resend.

Contact properties

Contact properties can be used to store additional information about your Contacts and then personalize your Broadcasts with dynamic content.

Included properties

Each Contact includes the following attributes:

email: The email address of the Contact. (required)
first_name: The first name of the Contact.
last_name: The last name of the Contact.
segments: A list of Segments the Contact belongs to.
topics: A list of Topics the Contact subscribes to.
unsubscribed: Whether the Contact is unsubscribed from all Broadcasts.
properties: An object of custom-defined properties, where each value includes the property's value and type.

Manage Contact properties

You can view, add, and manage your Contact properties in the Properties Dashboard view or programmatically with the Contact properties API, Resend CLI commands, and MCP.

You can also create Automations to update Contact properties.

Add Custom Contact properties

You can create additional custom Contact properties for your Contacts to store additional information. These properties can be used to personalize your Broadcasts across all Segments.

Each Contact Property has a key, a value, and optional fallback value.

key: The key of the property (must be alphanumeric and underscore only, max 50 characters). This is case sensitive.
value: The value of the property (may be a string or number).
fallback_value: The fallback value of the property (must match the type of the property).

Video

You can also create Contact properties via the API or SDKs.

Node.js

import { Resend } from 'resend';

const resend = new Resend('re_xxxxxxxxx');

const { data, error } = await resend.contactProperties.create({
  key: 'company_name',
  type: 'string',
  fallbackValue: 'Acme Corp',
});

PHP

$resend = Resend::client('re_xxxxxxxxx');

$resend->contactProperties->create([
  'key' => 'company_name',
  'type' => 'string',
  'fallback_value' => 'Acme Corp',
]);

Python

import resend

resend.api_key = 're_xxxxxxxxx'

params: resend.ContactProperties.CreateParams = {
    "key": "company_name",
    "type": "string",
    "fallback_value": "Acme Corp",
}

contact_property = resend.ContactProperties.create(params)

Ruby

require "resend"

Resend.api_key = "re_xxxxxxxxx"

property = Resend::ContactProperties.create({
  key: "company_name",
  type: "string",
  fallback_value: "Acme Corp"
})

package main

import (
	"context"
	"fmt"

	"github.com/resend/resend-go/v4"
)

func main() {
	ctx := context.TODO()
	apiKey := "re_xxxxxxxxx"

	client := resend.NewClient(apiKey)

	params := &resend.CreateContactPropertyRequest{
		Key:           "company_name",
		Type:          "string",
		FallbackValue: "Acme Corp",
	}

	property, err := client.ContactProperties.CreateWithContext(ctx, params)
	if err != nil {
		panic(err)
	}
	fmt.Println(property)
}

Rust

use resend_rs::{
  types::{CreateContactPropertyOptions, PropertyType},
  Resend, Result,
};

#[tokio::main]
async fn main() -> Result<()> {
  let resend = Resend::new("re_xxxxxxxxx");

  let contact_property = CreateContactPropertyOptions::new("company_name", PropertyType::String)
    .with_fallback("Acme Corp");

  let _contact_property = resend.contacts.create_property(contact_property).await?;

  Ok(())
}

Java

import com.resend.*;
import com.resend.core.exception.ResendException;
import com.resend.services.contactproperties.model.CreateContactPropertyOptions;

public class Main {
  public static void main(String[] args) throws ResendException {
    Resend resend = new Resend("re_xxxxxxxxx");

    CreateContactPropertyOptions options = CreateContactPropertyOptions.builder()
      .key("company_name")
      .type("string")
      .fallbackValue("Acme Corp")
      .build();

    resend.contactProperties().create(options);
  }
}

.NET

using Resend;

IResend resend = ResendClient.Create( "re_xxxxxxxxx" ); // Or from DI

var resp = await resend.ContactPropCreateAsync( new ContactPropertyData() {
  Key = "company_name",
  PropertyType = ContactPropertyType.String,
  DefaultValue = "Acme Corp",
} );
Console.WriteLine( "Prop Id={0}", resp.Content );

cURL

curl -X POST 'https://api.resend.com/contact-properties' \
     -H 'Authorization: Bearer re_xxxxxxxxx' \
     -H 'Content-Type: application/json' \
     -d $'{
  "key": "company_name",
  "type": "string",
  "fallback_value": "Acme Corp"
}'

Add properties to a Contact

When you create a Contact property with a fallback value, that default is used for Contacts that do not have a custom value for the property. If no fallback is provided, the Contact will not have a value for that property.

To update this value for a Contact in the Dashboard:

Go to the **Contacts** Dashboard view.
Click the **More options** button and then **Edit Contact**.
Add the property key and value.
Click the **Save** button.

Video

Add or update property values programmatically

You can add custom property values to a Contact when you create a Contact with the API or from the terminal with a CLI command.

Node.js

import { Resend } from 'resend';const resend = new Resend('re_xxxxxxxxx');const { data, error } = await resend.contacts.create({  email: 'steve.wozniak@gmail.com',  firstName: 'Steve',  lastName: 'Wozniak',  unsubscribed: false,  properties: {    company_name: 'Acme Corp',  },});

PHP

$resend = Resend::client('re_xxxxxxxxx');$resend->contacts->create(  parameters: [    'email' => 'steve.wozniak@gmail.com',    'first_name' => 'Steve',    'last_name' => 'Wozniak',    'unsubscribed' => false,    'properties' => [      'company_name' => 'Acme Corp',    ]  ]);

Python

import resendresend.api_key = "re_xxxxxxxxx"params: resend.Contacts.CreateParams = {  "email": "steve.wozniak@gmail.com",  "first_name": "Steve",  "last_name": "Wozniak",  "unsubscribed": False,  "properties": {    "company_name": "Acme Corp"  }}resend.Contacts.create(params)

Ruby

require "resend"Resend.api_key = "re_xxxxxxxxx"params = {  "email": "steve.wozniak@gmail.com",  "first_name": "Steve",  "last_name": "Wozniak",  "unsubscribed": false,  "properties": {    "company_name": "Acme Corp",  }}Resend::Contacts.create(params)

import "github.com/resend/resend-go/v4"client := resend.NewClient("re_xxxxxxxxx")params := &resend.CreateContactRequest{  Email:        "steve.wozniak@gmail.com",  FirstName:    "Steve",  LastName:     "Wozniak",  Unsubscribed: false,  Properties: map[string]interface{} {    "company_name": "Acme Corp",  },}client.Contacts.Create(params)

Rust

use resend_rs::{types::CreateContactOptions, Resend, Result};use std::collections::HashMap;#[tokio::main]async fn main() -> Result<()> {  let resend = Resend::new("re_xxxxxxxxx");  let contact = CreateContactOptions::new("steve.wozniak@gmail.com")    .with_first_name("Steve")    .with_last_name("Wozniak")    .with_unsubscribed(false)    .with_properties(HashMap::from([(      "company_name".to_string(),      "Acme Corp".to_string(),    )]));  let _contact = resend.contacts.create(contact).await?;  Ok(())}

Java

import com.resend.*;import com.resend.core.exception.ResendException;import com.resend.services.contacts.model.CreateContactOptions;import com.resend.services.contacts.model.CreateContactResponseSuccess;public class Main {    public static void main(String[] args) throws ResendException {        Resend resend = new Resend("re_xxxxxxxxx");        CreateContactOptions params = CreateContactOptions.builder()                .email("steve.wozniak@gmail.com")                .firstName("Steve")                .lastName("Wozniak")                .unsubscribed(false)                .properties(java.util.Map.of("company_name", "Acme Corp"))                .build();        CreateContactResponseSuccess data = resend.contacts().create(params);    }}

.NET

using Resend;IResend resend = ResendClient.Create( "re_xxxxxxxxx" ); // Or from DIvar resp = await resend.ContactAddAsync(    new ContactData()    {        Email = "steve.wozniak@gmail.com",        FirstName = "Steve",        LastName = "Wozniak",        IsUnsubscribed = false,        Properties = new Dictionary<string, object?> {          { "company_name", "Acme Corp" }        }    });Console.WriteLine( "Contact Id={0}", resp.Content );

cURL

curl -X POST 'https://api.resend.com/contacts' \     -H 'Authorization: Bearer re_xxxxxxxxx' \     -H 'Content-Type: application/json' \     -d $'{  "email": "steve.wozniak@gmail.com",  "first_name": "Steve",  "last_name": "Wozniak",  "unsubscribed": false,  "properties": {    "company_name": "Acme Corp",  }}'

You can also update a Contact to add or change a property value using the update Contact endpoint or CLI command.

Node.js

import { Resend } from 'resend';const resend = new Resend('re_xxxxxxxxx');const { data, error } = await resend.contacts.update({  id: 'e169aa45-1ecf-4183-9955-b1499d5701d3',  // or: email: 'acme@example.com',  properties: {    company_name: 'Acme Corp',  },});

PHP

$resend = Resend::client('re_xxxxxxxxx');

// Update by contact id
$resend->contacts->update(
  idOrEmail: 'e169aa45-1ecf-4183-9955-b1499d5701d3',
  parameters: [
    'properties' => [
      'company_name' => 'Acme Corp',
    ]
  ]
);

// Update by contact email
$resend->contacts->update(
  idOrEmail: 'acme@example.com',
  parameters: [
    'properties' => [
      'company_name' => 'Acme Corp',
    ]
  ]
);

Python

import resend

resend.api_key = "re_xxxxxxxxx"

# Update by contact id
params: resend.Contacts.UpdateParams = {
  "id": "e169aa45-1ecf-4183-9955-b1499d5701d3",
  "properties": {
    "company_name": "Acme Corp",
  }
}

resend.Contacts.update(params)

# Update by contact email
params: resend.Contacts.UpdateParams = {
  "email": "acme@example.com",
  "properties": {
    "company_name": "Acme Corp",
  }
}

resend.Contacts.update(params)

Ruby

require "resend"

Resend.api_key = "re_xxxxxxxxx"

# Update by contact id
params = {
  "id": "e169aa45-1ecf-4183-9955-b1499d5701d3",
  "properties": {
    "company_name": "Acme Corp",
  }
}

Resend::Contacts.update(params)

# Update by contact email
params = {
  "email": "acme@example.com",
  "properties": {
    "company_name": "Acme Corp",
  }
}

Resend::Contacts.update(params)

import "github.com/resend/resend-go/v4"

client := resend.NewClient("re_xxxxxxxxx")

// Update by contact id
params := &resend.UpdateContactRequest{
  Id:           "e169aa45-1ecf-4183-9955-b1499d5701d3",
  Properties: map[string]interface{}{
    "company_name": "Acme Corp",
  },
}
params.SetUnsubscribed(true)

client.Contacts.Update(params)

// Update by contact email
params = &resend.UpdateContactRequest{
  Email:        "acme@example.com",
  Properties: map[string]interface{}{
    "company_name": "Acme Corp",
  },
}
params.SetUnsubscribed(true)

client.Contacts.Update(params)

Rust

use resend_rs::{types::ContactChanges, Resend, Result};use std::collections::HashMap;#[tokio::main]async fn main() -> Result<()> {  let resend = Resend::new("re_xxxxxxxxx");  let changes = ContactChanges::new().with_properties(HashMap::from([(    "company_name".to_string(),    "Acme Corp".to_string(),  )]));  // Update by contact id  let _contact = resend    .contacts    .update("e169aa45-1ecf-4183-9955-b1499d5701d3", changes.clone())    .await?;  // Update by contact email  let _contact = resend    .contacts    .update("acme@example.com", changes)    .await?;  Ok(())}

Java

import com.resend.*;import com.resend.core.exception.ResendException;import com.resend.services.contacts.model.UpdateContactOptions;import com.resend.services.contacts.model.UpdateContactResponseSuccess;public class Main {    public static void main(String[] args) throws ResendException {        Resend resend = new Resend("re_xxxxxxxxx");        UpdateContactOptions params = UpdateContactOptions.builder()                .id("e169aa45-1ecf-4183-9955-b1499d5701d3") // or: .email("acme@example.com")                .properties(java.util.Map.of("company_name", "Acme Corp"))                .build();        UpdateContactResponseSuccess data = resend.contacts().update(params);    }}

.NET

using Resend;

IResend resend = ResendClient.Create( "re_xxxxxxxxx" ); // Or from DI

// By Id
await resend.ContactUpdateAsync(
    contactId: new Guid( "e169aa45-1ecf-4183-9955-b1499d5701d3" ),
    new ContactData()
    {
        FirstName = "Stevie",
        LastName = "Wozniaks",
        Properties = new Dictionary<string, object?> {
          { "company_name", "Acme Corp" }
        }
    }
);

// By Email
await resend.ContactUpdateByEmailAsync(
    "acme@example.com",
    new ContactData()
    {
        FirstName = "Stevie",
        LastName = "Wozniaks",
        Properties = new Dictionary<string, object?> {
          { "company_name", "Acme Corp" }
        }
    }
);

cURL

# Update by contact id
curl -X PATCH 'https://api.resend.com/contacts/520784e2-887d-4c25-b53c-4ad46ad38100' \
     -H 'Authorization: Bearer re_xxxxxxxxx' \
     -H 'Content-Type: application/json' \
     -d $'{
  "properties": {
    "company_name": "Acme Corp",
  }
}'

# Update by contact email
curl -X PATCH 'https://api.resend.com/contacts/acme@example.com' \
     -H 'Authorization: Bearer re_xxxxxxxxx' \
     -H 'Content-Type: application/json' \
     -d $'{
  "properties": {
    "company_name": "Acme Corp",
  }
}'

When you create or update a Contact with properties, the properties are added to the Contact only if the property key already exists and the value type is valid.

If the properties don't exist, or the values are of the wrong type, they are not added to the Contact and the call fails. An error is returned.

You can list all Contact properties with the API to see and verify all available properties.

Use Contact properties in Broadcasts

You can use Contact properties in your Broadcasts to personalize your emails.

Video

You can also use Contact properties in your Broadcast HTML and Text content when you create a Broadcast using the API or SDKs.

API Reference

For complete API documentation, see the Contact properties API reference.

Search documentation

Get started

Learn

Resources

Contact properties

Contact properties

Included properties

Manage Contact properties

Add Custom Contact properties

Add properties to a Contact

Add or update property values programmatically

Use Contact properties in Broadcasts

API Reference

Get started

Learn

Resources