> ## Documentation Index
> Fetch the complete documentation index at: https://docs.autosend.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Contact

> Creates a new contact in your AutoSend project.

export const APP_PATHS = {
  home: '/',
  quickstart: '/quickstart',
  domainConfiguration: '/domain',
  apiReference: '/api-reference',
  sendEmail: '/api-reference/mails/send',
  bulkSendEmail: '/api-reference/mails/bulk',
  upsertContactApiRef: '/api-reference/contacts/upsert-contact',
  transactional: '/transactional-emails',
  emailActivity: '/transactional-emails/email-activity',
  emailTemplates: '/transactional-emails/email-templates',
  sendingEmail: '/quickstart/email-using-api',
  transactionalTroubleshooting: '/transactional-emails/troubleshooting',
  marketing: '/marketing-emails',
  campaigns: '/marketing-emails/campaigns',
  contacts: '/marketing-emails/contacts',
  contactsIntroduction: '/marketing-emails/contacts/introduction',
  contactsImportCsv: '/marketing-emails/contacts/import-csv',
  contactsLists: '/marketing-emails/contacts/lists',
  contactsSegments: '/marketing-emails/contacts/segments',
  contactsCustomFields: '/marketing-emails/contacts/custom-fields',
  sender: '/marketing-emails/sender',
  unsubscribeGroups: '/others/unsubscribe-groups',
  webhookIntroduction: '/others/webhooks/introduction',
  webhookEventType: '/others/webhooks/event-type',
  webhookRetries: '/others/webhooks/retries',
  webhookVerifyRequests: '/others/webhooks/verify-requests',
  dynamicTemplates: '/dynamic-templates',
  guides: '/guides',
  sitemap: '/sitemap.xml',
  team: '/others/team',
  automations: '/automations',
  smtpIntroduction: '/quickstart/smtp',
  betterAuth: '/guides/better-auth',
  templateVariables: '/transactional-emails/variables',
  suppressions: '/others/suppressions',
  rateLimit: '/api-reference/rate-limit',
  nodejsSdk: '/sdk/nodejs',
  smtpIntegrationGuides: '/guides/smtp',
  apiKeys: '/api-keys',
  apiReferenceIntroduction: '/api-reference/introduction',
  lovableGuide: '/ai/integrations/lovable',
  aiIntroduction: '/ai/introduction',
  aiSkills: '/ai/skills',
  aiMcpServer: '/ai/mcp-server',
  aiLovable: '/ai/integrations/lovable',
  aiBolt: '/ai/integrations/bolt',
  aiV0: '/ai/integrations/v0',
  aiReplit: '/ai/integrations/replit',
  mcpClaude: '/ai/mcp-clients/claude',
  mcpCursor: '/ai/mcp-clients/cursor',
  mcpCopilot: '/ai/mcp-clients/copilot',
  mcpWindsurf: '/ai/mcp-clients/windsurf',
  mcpCodex: '/ai/mcp-clients/codex',
  mcpAntigravity: '/ai/mcp-clients/antigravity',
  mcpChatgpt: '/ai/mcp-clients/chatgpt',
  mcpRaycast: '/ai/mcp-clients/raycast',
  domainWarmup: '/marketing-emails/domain-warmup',
  projects: '/projects',
  createAutomationApi: '/api-reference/automations/create-automation'
};

export const AUTOSEND_PATHS = {
  dashboard: 'https://autosend.com/dashboard',
  apiKey: 'https://autosend.com/account/api-key',
  faqs: 'https://autosend.com/faq',
  marketingEmails: 'https://autosend.com/marketing-emails',
  webhooks: 'https://autosend.com/webhooks',
  composeByAutoSend: 'https://autosend.com/compose',
  emailActivity: 'https://autosend.com/email-activities',
  team: 'https://autosend.com/settings/team',
  pricing: 'https://autosend.com/pricing',
  verifyEmail: 'https://autosend.com/compose/email-builder?template=verify-email',
  welcomeEmail: 'https://autosend.com/compose/email-builder?template=welcome-email',
  productUpdate: 'https://autosend.com/compose/email-builder?template=product-update',
  newsletter: 'https://autosend.com/compose/email-builder?template=newsletter',
  automations: 'https://autosend.com/automations',
  globalSuppressions: 'https://autosend.com/suppressions/global',
  signup: 'https://autosend.com/signup',
  domains: 'https://autosend.com/settings/domains',
  logoKit: 'https://asend.email/logo',
  contactsPage: 'https://autosend.com/contacts/list-and-segments'
};

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.autosend.com/v1/contacts \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
    "email": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "userId": "user_12345",
    "customFields": {
      "company": "Acme Corp",
      "role": "Developer",
      "plan": "premium"
    }
  }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.autosend.com/v1/contacts"

  headers = {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
  }

  payload = {
      "email": "john.doe@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "userId": "user_12345",
      "customFields": {
          "company": "Acme Corp",
          "role": "Developer",
          "plan": "premium"
      }
  }

  response = requests.post(url, json=payload, headers=headers)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  fetch('https://api.autosend.com/v1/contacts', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer <token>',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      email: 'john.doe@example.com',
      firstName: 'John',
      lastName: 'Doe',
      userId: 'user_12345',
      customFields: {
        company: 'Acme Corp',
        role: 'Developer',
        plan: 'premium'
      }
    })
  })
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(error => console.error('Error:', error));
  ```

  ```php PHP theme={null}
  <?php

  $url = 'https://api.autosend.com/v1/contacts';

  $data = [
      'email' => 'john.doe@example.com',
      'firstName' => 'John',
      'lastName' => 'Doe',
      'userId' => 'user_12345',
      'customFields' => [
          'company' => 'Acme Corp',
          'role' => 'Developer',
          'plan' => 'premium'
      ]
  ];

  $ch = curl_init($url);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'Authorization: Bearer <token>',
      'Content-Type: application/json'
  ]);

  $response = curl_exec($ch);
  curl_close($ch);

  echo $response;
  ?>
  ```

  ```go Go theme={null}
  package main

  import (
      "bytes"
      "encoding/json"
      "fmt"
      "net/http"
  )

  func main() {
      url := "https://api.autosend.com/v1/contacts"
      
      payload := map[string]interface{}{
          "email":     "john.doe@example.com",
          "firstName": "John",
          "lastName": "Doe",
          "userId":    "user_12345",
          "customFields": map[string]string{
              "company": "Acme Corp",
              "role":    "Developer",
              "plan":    "premium",
          },
      }
      
      jsonData, _ := json.Marshal(payload)
      
      req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
      req.Header.Set("Authorization", "Bearer <token>")
      req.Header.Set("Content-Type", "application/json")
      
      client := &http.Client{}
      resp, err := client.Do(req)
      if err != nil {
          fmt.Println("Error:", err)
          return
      }
      defer resp.Body.Close()
      
      fmt.Println("Response Status:", resp.Status)
  }
  ```

  ```java Java theme={null}
  import java.io.OutputStream;
  import java.net.HttpURLConnection;
  import java.net.URL;
  import java.nio.charset.StandardCharsets;

  public class CreateContact {
      public static void main(String[] args) {
          try {
              URL url = new URL("https://api.autosend.com/v1/contacts");
              HttpURLConnection con = (HttpURLConnection) url.openConnection();
              
              con.setRequestMethod("POST");
              con.setRequestProperty("Authorization", "Bearer <token>");
              con.setRequestProperty("Content-Type", "application/json");
              con.setDoOutput(true);
              
              String jsonInputString = "{\n" +
                  "  \"email\": \"john.doe@example.com\",\n" +
                  "  \"firstName\": \"John\",\n" +
                  "  \"lastName\": \"Doe\",\n" +
                  "  \"userId\": \"user_12345\",\n" +
                  "  \"customFields\": {\n" +
                  "    \"company\": \"Acme Corp\",\n" +
                  "    \"role\": \"Developer\",\n" +
                  "    \"plan\": \"premium\"\n" +
                  "  }\n" +
                  "}";
              
              try (OutputStream os = con.getOutputStream()) {
                  byte[] input = jsonInputString.getBytes(StandardCharsets.UTF_8);
                  os.write(input, 0, input.length);
              }
              
              int status = con.getResponseCode();
              System.out.println("Response Status: " + status);
              
          } catch (Exception e) {
              e.printStackTrace();
          }
      }
  }
  ```

  ```ruby Ruby theme={null}
  require 'net/http'
  require 'json'
  require 'uri'

  uri = URI('https://api.autosend.com/v1/contacts')

  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true

  request = Net::HTTP::Post.new(uri.path)
  request['Authorization'] = 'Bearer <token>'
  request['Content-Type'] = 'application/json'

  request.body = {
    email: 'john.doe@example.com',
    firstName: 'John',
    lastName: 'Doe',
    userId: 'user_12345',
    customFields: {
      company: 'Acme Corp',
      role: 'Developer',
      plan: 'premium'
    }
  }.to_json

  response = http.request(request)
  puts response.body
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "id": "507f1f77bcf86cd799439011",
      "email": "john.doe@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "userId": "user_12345",
      "customFields": {
        "company": "Acme Corp",
        "role": "Developer",
        "plan": "premium"
      },
      "updatedAt": "2024-01-15T10:30:00.000Z",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "projectId": "229f1f77bcf86cd9273048038"
    }
  }
  ```
</ResponseExample>

<Note>
  Use this API when you know the contact is new. Use <a href={APP_PATHS.upsertContactApiRef} target="_blank" title="Upsert Contact">Upsert Contact</a> when the contact may already exist. It will create or update without throwing an error.
</Note>

### Authorizations

<ParamField path="Authorizations" type="string | header" required>
  Bearer authentication header of the form Bearer `<token>`, where `<token>` is your auth token.
</ParamField>

### Body

Contact information to create

<ParamField path="email" type="string<email>" required>
  Valid email address (automatically normalized to lowercase)

  Example: `"john.doe@example.com"`
</ParamField>

<ParamField path="firstName" type="string">
  Contact's first name

  Example: `"John"`
</ParamField>

<ParamField path="lastName" type="string">
  Contact's last name

  Example: `"Doe"`
</ParamField>

<ParamField path="userId" type="string">
  An optional reference field to store your application's user ID. Use this to map your internal users to AutoSend contacts.

  Example: `"user_12345"`
</ParamField>

<ParamField path="listIds" type="array">
  IDs of the contact lists to add this contact to. You can find list IDs in your <a href={AUTOSEND_PATHS.contactsPage} target="_blank" title="AutoSend Dashboard">AutoSend Dashboard</a>.

  Do not pass segment IDs here. Segments are computed automatically based on contact field values. Adding a contact to a list will also trigger any live automations associated with that list.

  Example: `["507f1f77bcf86cd799439011"]`
</ParamField>

<ParamField path="customFields" type="object">
  Key-value pairs for custom contact attributes. There are four supported value types: `string`, `number`, `boolean`, and `date`. Learn more about <a href={APP_PATHS.contactsCustomFields} target="_blank" title="Custom Field">custom fields</a>.

  <Expandable title="child attributes">
    <ResponseField name="customFields.{key}" type="string" />
  </Expandable>

  Example:

  ```jsx theme={null}
  customFields: {
    "company": "Acme Corp",
    "isPremium": true,
    "loginCount": 42,
    "trialEndsAt": "2024-03-01"
  }
  ```
</ParamField>

### Response

<span className="text-sm">Contact created successfully</span>

<ResponseField name="success" type="boolean">
  Indicates if the request was successful

  Example: `true`
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="child attributes">
    <ResponseField name="data.id" type="string">
      Contact ID

      Example: `"507f1f77bcf86cd799439011"`
    </ResponseField>

    <ResponseField name="data.email" type="string">
      Contact email address

      Example: `"john.doe@example.com"`
    </ResponseField>

    <ResponseField name="data.firstName" type="string">
      Contact's first name

      Example: `"John"`
    </ResponseField>

    <ResponseField name="data.lastName" type="string">
      Contact's last name

      Example: `"Doe"`
    </ResponseField>

    <ResponseField name="data.userId" type="string">
      Your application's user identifier

      Example: `"user_12345"`
    </ResponseField>

    <ResponseField name="data.customFields" type="object">
      Custom contact attributes

      <Expandable title="child attributes">
        <ResponseField name="customFields.{key}" type="string" />
      </Expandable>

      Example:

      ```jsx theme={null}
      {
        "company": "Acme Corp",
        "role": "Developer",
        "plan": "premium"
      }
      ```
    </ResponseField>

    <ResponseField name="data.createdAt" type="string">
      Contact creation timestamp

      Example: `"2024-01-15T10:30:00.000Z"`
    </ResponseField>

    <ResponseField name="data.updatedAt" type="string">
      Contact last update timestamp

      Example: `"2024-01-15T10:30:00.000Z"`
    </ResponseField>

    <ResponseField name="data.projectId" type="string">
      Project ID that the contact belongs to

      Example: `"229f1f77bcf86cd9273048038"`
    </ResponseField>

    <ResponseField name="data.listIds" type="array">
      Contact List IDs

      Example: `["507f1f77bcf86cd799439011"]`
    </ResponseField>
  </Expandable>
</ResponseField>


## OpenAPI

````yaml POST /contacts
openapi: 3.1.0
info:
  title: AutoSend API
  description: AutoSend REST API for managing contacts and sending emails
  version: 1.0.0
servers:
  - url: https://api.autosend.com/v1
security:
  - bearerAuth: []
paths:
  /contacts:
    post:
      summary: Create Contact
      description: Creates a new contact in your AutoSend project.
components: {}

````