Create Contact Import

POST

contacts

imports

Node.js

import { readFile } from 'node:fs/promises';
import { Resend } from 'resend';

const resend = new Resend('re_xxxxxxxxx');

const file = new Blob([await readFile('contacts.csv')], {
  type: 'text/csv',
});

const { data, error } = await resend.contacts.imports.create({
  file,
  columnMap: {
    email: 'Email',
    firstName: 'First Name',
    lastName: 'Last Name',
    properties: {
      plan: {
        column: 'Plan',
        type: 'string',
      },
    },
  },
  onConflict: 'upsert',
  segments: [{ id: '78e7a5c6-9a91-4c63-9d1f-3b9c0b5b9ab6' }],
  topics: [
    {
      id: '059ac693-2fc8-4c13-8b27-01350d638a17',
      subscription: 'opt_in',
    },
  ],
});

PHP

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

$file = fopen('contacts.csv', 'r');

$resend->contacts->imports->create([
  'file' => $file,
  'column_map' => [
    'email' => 'Email',
    'first_name' => 'First Name',
    'last_name' => 'Last Name',
    'properties' => [
      'plan' => [
        'column' => 'Plan',
        'type' => 'string',
      ],
    ],
  ],
  'on_conflict' => 'upsert',
  'segments' => [['id' => '78e7a5c6-9a91-4c63-9d1f-3b9c0b5b9ab6']],
  'topics' => [
    [
      'id' => '059ac693-2fc8-4c13-8b27-01350d638a17',
      'subscription' => 'opt_in',
    ],
  ],
]);

Python

import resend

resend.api_key = "re_xxxxxxxxx"

with open("contacts.csv", "rb") as f:
    file_content = f.read()

params: resend.Contacts.Imports.CreateParams = {
    "file": file_content,
    "column_map": {
        "email": "Email",
        "first_name": "First Name",
        "last_name": "Last Name",
        "properties": {
            "plan": {
                "column": "Plan",
                "type": "string",
            },
        },
    },
    "on_conflict": "upsert",
    "segments": [{"id": "78e7a5c6-9a91-4c63-9d1f-3b9c0b5b9ab6"}],
    "topics": [
        {
            "id": "059ac693-2fc8-4c13-8b27-01350d638a17",
            "subscription": "opt_in",
        },
    ],
}

resend.Contacts.Imports.create(params)

Ruby

require "resend"

Resend.api_key = "re_xxxxxxxxx"

params = {
  file: File.read("contacts.csv"),
  column_map: {
    "email" => "Email",
    "first_name" => "First Name",
    "last_name" => "Last Name",
    "properties" => {
      "plan" => {
        "column" => "Plan",
        "type" => "string"
      }
    }
  },
  on_conflict: "upsert",
  segments: [{ id: "78e7a5c6-9a91-4c63-9d1f-3b9c0b5b9ab6" }],
  topics: [
    { id: "059ac693-2fc8-4c13-8b27-01350d638a17", subscription: "opt_in" }
  ]
}

Resend::Contacts::Imports.create(params)

package main

import (
	"os"

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

func main() {
	client := resend.NewClient("re_xxxxxxxxx")

	file, err := os.ReadFile("contacts.csv")
	if err != nil {
		panic(err)
	}

	params := &resend.CreateContactImportRequest{
		File:       file,
		Filename:   "contacts.csv",
		OnConflict: "upsert",
		ColumnMap: map[string]any{
			"email":      "Email",
			"first_name": "First Name",
			"last_name":  "Last Name",
			"properties": map[string]any{
				"plan": map[string]any{
					"column": "Plan",
					"type":   "string",
				},
			},
		},
		Segments: []resend.ContactImportSegment{{Id: "78e7a5c6-9a91-4c63-9d1f-3b9c0b5b9ab6"}},
		Topics: []resend.TopicSubscriptionUpdate{
			{Id: "059ac693-2fc8-4c13-8b27-01350d638a17", Subscription: "opt_in"},
		},
	}

	client.Contacts.Imports.Create(params)
}

Rust

use std::fs::File;

use resend_rs::{
  Resend, Result,
  types::{
    ContactImportColumnMap, ContactImportOnConflict, ContactImportPropertyMapping,
    ContactImportPropertyType, ContactImportTopic, ContactImportTopicSubscription,
    CreateContactImportOptions,
  },
};

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

  let file = File::open("contacts.csv").unwrap();

  let contact_import = CreateContactImportOptions::new()
    .with_column_map(
      ContactImportColumnMap::new()
        .with_email("Email")
        .with_first_name("First Name")
        .with_last_name("Last Name")
        .with_property(
          "plan",
          ContactImportPropertyMapping {
            column: "Plan".to_owned(),
            r#type: ContactImportPropertyType::String,
          },
        ),
    )
    .with_on_conflict(ContactImportOnConflict::Upsert)
    .with_segment("78e7a5c6-9a91-4c63-9d1f-3b9c0b5b9ab6")
    .with_topic(ContactImportTopic {
      id: "059ac693-2fc8-4c13-8b27-01350d638a17".to_owned(),
      subscription: ContactImportTopicSubscription::OptIn,
    });

  let _data = resend.contacts.create_import(file, contact_import).await?;

  Ok(())
}

Java

import com.resend.Resend;
import com.resend.services.contacts.model.*;
import java.io.File;

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

        ContactImportColumnMap columnMap = ContactImportColumnMap.builder()
                .email("Email")
                .firstName("First Name")
                .lastName("Last Name")
                .property("plan", ContactImportPropertyMapping.builder()
                        .column("Plan")
                        .type("string")
                        .build())
                .build();

        CreateContactImportOptions params = CreateContactImportOptions.builder()
                .file(new File("contacts.csv"))
                .columnMap(columnMap)
                .onConflict("upsert")
                .segments(new ContactImportSegmentReference("78e7a5c6-9a91-4c63-9d1f-3b9c0b5b9ab6"))
                .topics(ContactImportTopicSubscription.builder()
                        .id("059ac693-2fc8-4c13-8b27-01350d638a17")
                        .subscription("opt_in")
                        .build())
                .build();

        CreateContactImportResponseSuccess data = resend.contacts().imports().create(params);
    }
}

cURL

curl -X POST 'https://api.resend.com/contacts/imports' \
     -H 'Authorization: Bearer re_xxxxxxxxx' \
     -F 'file=@contacts.csv;type=text/csv' \
     -F 'column_map={"email":"Email","first_name":"First Name","last_name":"Last Name","properties":{"plan":{"column":"Plan","type":"string"}}}' \
     -F 'on_conflict=upsert' \
     -F 'segments=[{"id":"78e7a5c6-9a91-4c63-9d1f-3b9c0b5b9ab6"}]' \
     -F 'topics=[{"id":"059ac693-2fc8-4c13-8b27-01350d638a17","subscription":"opt_in"}]'

CLI

resend contacts imports create \
  --file contacts.csv \
  --column-map '{"email":"Email","firstName":"First Name","lastName":"Last Name","properties":{"plan":{"column":"Plan","type":"string"}}}' \
  --on-conflict upsert \
  --segment-id 78e7a5c6-9a91-4c63-9d1f-3b9c0b5b9ab6 \
  --topics '[{"id":"059ac693-2fc8-4c13-8b27-01350d638a17","subscription":"opt_in"}]'

Response

{
  "object": "contact_import",
  "id": "479e3145-dd38-476b-932c-529ceb705947"
}

Body Parameters

This endpoint accepts multipart/form-data. Object and array fields (column_map, segments, topics) must be sent as JSON-encoded strings.

file

required

The CSV file to import. The file must be sent as a form field named file. Maximum file size is 200MB.

object

Maps CSV columns to contact fields.

Hide column_map

string

The CSV column that contains contact email addresses.

string

The CSV column that contains contact first names.

string

The CSV column that contains contact last names.

string

The CSV column that contains the contact’s global subscription status.

object

A map of custom property keys to CSV columns.

Show properties

object

The custom property key.

Show property mapping

string

required

The CSV column that contains the custom property value.

'string' | 'number' | 'boolean'

The custom property value type. Defaults to string.

'upsert' | 'skip'

How to handle contacts that already exist. Defaults to upsert.

array

Array of objects. Each object must contain the ID of the segment that you’d like to add the imported contacts to.

Hide segments

string

required

The segment UUID.

array

Array of topic subscriptions for imported contacts.

Hide topics

string

required

The Topic UUID.

'opt_in' | 'opt_out'

required

The subscription status for this topic.

Node.js

import { readFile } from 'node:fs/promises';
import { Resend } from 'resend';

const resend = new Resend('re_xxxxxxxxx');

const file = new Blob([await readFile('contacts.csv')], {
  type: 'text/csv',
});

const { data, error } = await resend.contacts.imports.create({
  file,
  columnMap: {
    email: 'Email',
    firstName: 'First Name',
    lastName: 'Last Name',
    properties: {
      plan: {
        column: 'Plan',
        type: 'string',
      },
    },
  },
  onConflict: 'upsert',
  segments: [{ id: '78e7a5c6-9a91-4c63-9d1f-3b9c0b5b9ab6' }],
  topics: [
    {
      id: '059ac693-2fc8-4c13-8b27-01350d638a17',
      subscription: 'opt_in',
    },
  ],
});

PHP

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

$file = fopen('contacts.csv', 'r');

$resend->contacts->imports->create([
  'file' => $file,
  'column_map' => [
    'email' => 'Email',
    'first_name' => 'First Name',
    'last_name' => 'Last Name',
    'properties' => [
      'plan' => [
        'column' => 'Plan',
        'type' => 'string',
      ],
    ],
  ],
  'on_conflict' => 'upsert',
  'segments' => [['id' => '78e7a5c6-9a91-4c63-9d1f-3b9c0b5b9ab6']],
  'topics' => [
    [
      'id' => '059ac693-2fc8-4c13-8b27-01350d638a17',
      'subscription' => 'opt_in',
    ],
  ],
]);

Python

import resend

resend.api_key = "re_xxxxxxxxx"

with open("contacts.csv", "rb") as f:
    file_content = f.read()

params: resend.Contacts.Imports.CreateParams = {
    "file": file_content,
    "column_map": {
        "email": "Email",
        "first_name": "First Name",
        "last_name": "Last Name",
        "properties": {
            "plan": {
                "column": "Plan",
                "type": "string",
            },
        },
    },
    "on_conflict": "upsert",
    "segments": [{"id": "78e7a5c6-9a91-4c63-9d1f-3b9c0b5b9ab6"}],
    "topics": [
        {
            "id": "059ac693-2fc8-4c13-8b27-01350d638a17",
            "subscription": "opt_in",
        },
    ],
}

resend.Contacts.Imports.create(params)

Ruby

require "resend"

Resend.api_key = "re_xxxxxxxxx"

params = {
  file: File.read("contacts.csv"),
  column_map: {
    "email" => "Email",
    "first_name" => "First Name",
    "last_name" => "Last Name",
    "properties" => {
      "plan" => {
        "column" => "Plan",
        "type" => "string"
      }
    }
  },
  on_conflict: "upsert",
  segments: [{ id: "78e7a5c6-9a91-4c63-9d1f-3b9c0b5b9ab6" }],
  topics: [
    { id: "059ac693-2fc8-4c13-8b27-01350d638a17", subscription: "opt_in" }
  ]
}

Resend::Contacts::Imports.create(params)

package main

import (
	"os"

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

func main() {
	client := resend.NewClient("re_xxxxxxxxx")

	file, err := os.ReadFile("contacts.csv")
	if err != nil {
		panic(err)
	}

	params := &resend.CreateContactImportRequest{
		File:       file,
		Filename:   "contacts.csv",
		OnConflict: "upsert",
		ColumnMap: map[string]any{
			"email":      "Email",
			"first_name": "First Name",
			"last_name":  "Last Name",
			"properties": map[string]any{
				"plan": map[string]any{
					"column": "Plan",
					"type":   "string",
				},
			},
		},
		Segments: []resend.ContactImportSegment{{Id: "78e7a5c6-9a91-4c63-9d1f-3b9c0b5b9ab6"}},
		Topics: []resend.TopicSubscriptionUpdate{
			{Id: "059ac693-2fc8-4c13-8b27-01350d638a17", Subscription: "opt_in"},
		},
	}

	client.Contacts.Imports.Create(params)
}

Rust

use std::fs::File;

use resend_rs::{
  Resend, Result,
  types::{
    ContactImportColumnMap, ContactImportOnConflict, ContactImportPropertyMapping,
    ContactImportPropertyType, ContactImportTopic, ContactImportTopicSubscription,
    CreateContactImportOptions,
  },
};

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

  let file = File::open("contacts.csv").unwrap();

  let contact_import = CreateContactImportOptions::new()
    .with_column_map(
      ContactImportColumnMap::new()
        .with_email("Email")
        .with_first_name("First Name")
        .with_last_name("Last Name")
        .with_property(
          "plan",
          ContactImportPropertyMapping {
            column: "Plan".to_owned(),
            r#type: ContactImportPropertyType::String,
          },
        ),
    )
    .with_on_conflict(ContactImportOnConflict::Upsert)
    .with_segment("78e7a5c6-9a91-4c63-9d1f-3b9c0b5b9ab6")
    .with_topic(ContactImportTopic {
      id: "059ac693-2fc8-4c13-8b27-01350d638a17".to_owned(),
      subscription: ContactImportTopicSubscription::OptIn,
    });

  let _data = resend.contacts.create_import(file, contact_import).await?;

  Ok(())
}

Java

import com.resend.Resend;
import com.resend.services.contacts.model.*;
import java.io.File;

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

        ContactImportColumnMap columnMap = ContactImportColumnMap.builder()
                .email("Email")
                .firstName("First Name")
                .lastName("Last Name")
                .property("plan", ContactImportPropertyMapping.builder()
                        .column("Plan")
                        .type("string")
                        .build())
                .build();

        CreateContactImportOptions params = CreateContactImportOptions.builder()
                .file(new File("contacts.csv"))
                .columnMap(columnMap)
                .onConflict("upsert")
                .segments(new ContactImportSegmentReference("78e7a5c6-9a91-4c63-9d1f-3b9c0b5b9ab6"))
                .topics(ContactImportTopicSubscription.builder()
                        .id("059ac693-2fc8-4c13-8b27-01350d638a17")
                        .subscription("opt_in")
                        .build())
                .build();

        CreateContactImportResponseSuccess data = resend.contacts().imports().create(params);
    }
}

cURL

curl -X POST 'https://api.resend.com/contacts/imports' \
     -H 'Authorization: Bearer re_xxxxxxxxx' \
     -F 'file=@contacts.csv;type=text/csv' \
     -F 'column_map={"email":"Email","first_name":"First Name","last_name":"Last Name","properties":{"plan":{"column":"Plan","type":"string"}}}' \
     -F 'on_conflict=upsert' \
     -F 'segments=[{"id":"78e7a5c6-9a91-4c63-9d1f-3b9c0b5b9ab6"}]' \
     -F 'topics=[{"id":"059ac693-2fc8-4c13-8b27-01350d638a17","subscription":"opt_in"}]'

CLI

resend contacts imports create \
  --file contacts.csv \
  --column-map '{"email":"Email","firstName":"First Name","lastName":"Last Name","properties":{"plan":{"column":"Plan","type":"string"}}}' \
  --on-conflict upsert \
  --segment-id 78e7a5c6-9a91-4c63-9d1f-3b9c0b5b9ab6 \
  --topics '[{"id":"059ac693-2fc8-4c13-8b27-01350d638a17","subscription":"opt_in"}]'

JSON

{
  "object": "contact_import",
  "id": "479e3145-dd38-476b-932c-529ceb705947"
}

Was this page helpful?

⌘I