Skip to main content
Resend Docs

Search documentation

Type to search this documentation.

On this pageOverview

Contact Properties

Contact Properties can be used to store additional information about your Contacts and then personalize your Broadcasts.

Resend includes a few default properties:

  • first_name: The first name of the contact.
  • last_name: The last name of the contact.
  • unsubscribed: Whether the contact is unsubscribed from all Broadcasts.
  • email: The email address of the contact.

Add Custom Contact Properties

Section titled “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).
  • 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"
})
Go
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

Section titled “Add Properties to a Contact”

When you create a Contact Property you can provide a fallback value. This value will be used whenever you don't provide a custom value for a Contact.

To provide a custom value for a Contact, you can use the dashboard:

  1. Go to the Contacts page.
  2. Click the more options button and then Edit Contact.
  3. Add the property key and value.
  4. Click on the Save button.

Video

You can also add properties to a Contact when you create a Contact.

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)
Go
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",  }}'

Or you can update a Contact to add or change a property value using the update contact endpoint.

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)
Go
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, but only if the property key already exists and the value type is valid. You can list all Contact Properties to see all available properties.

What happens if the properties don't exist?

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

Property keys are case sensitive, right?

Yes, property keys are case sensitive. If you create a property with a key of "company_name", you cannot use "CompanyName" or "company_Name" in your Contacts.

What happens if the value isn't the right type?

If the value isn't the right type, the property value is not added to the Contact and the call fails. An error is returned.

Use Contact Properties in Broadcasts

Section titled “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.

Suggest an edit

Propose a replacement for this page. The site team reviews it before applying any changes.

Export
Documentation menu