Import contacts

Request body

• contactsarray<object>required

  The contacts to add, 1 to 10,000 per request.

  • emailstringrequired

    Their email address. Case does not matter: Ada@Example.com and ada@example.com are the same contact.

  • namestring

    Their name, as it should appear in your emails.

  • attributesobject

    Custom fields as key–value pairs, for example {"city": "Lagos", "plan": "pro"}. Use the keys from GET /contact-fields; a key your account has not seen before is kept too.

• list_idstring

  Optional. The ID of a list to put every address in this request on, new contacts and ones you already had. Copy it from Contacts → Lists in the dashboard, or read it from GET /contact-lists.

Request

curl -X POST 'https://app.mailyte.com/api/v1/contacts/import' \
  -H 'Authorization: Bearer mk_live_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "list_id": "01JBT8XQ2M9WYC3K4F6R7S8T9V",
    "contacts": [
      {
        "email": "ada@example.com",
        "name": "Ada Obi"
      },
      {
        "email": "tunde@example.com",
        "name": "Tunde Bello",
        "attributes": {
          "city": "Lagos",
          "plan": "pro"
        }
      }
    ]
  }'

const response = await fetch('https://app.mailyte.com/api/v1/contacts/import', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer mk_live_YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "list_id": "01JBT8XQ2M9WYC3K4F6R7S8T9V",
    "contacts": [
      {
        "email": "ada@example.com",
        "name": "Ada Obi"
      },
      {
        "email": "tunde@example.com",
        "name": "Tunde Bello",
        "attributes": {
          "city": "Lagos",
          "plan": "pro"
        }
      }
    ]
  }),
});
const { data } = await response.json();

import requests
response = requests.post(
    "https://app.mailyte.com/api/v1/contacts/import",
    headers={"Authorization": "Bearer mk_live_YOUR_API_KEY"},
    json={
      "list_id": "01JBT8XQ2M9WYC3K4F6R7S8T9V",
      "contacts": [
        {
          "email": "ada@example.com",
          "name": "Ada Obi"
        },
        {
          "email": "tunde@example.com",
          "name": "Tunde Bello",
          "attributes": {
            "city": "Lagos",
            "plan": "pro"
          }
        }
      ]
    },
)
data = response.json()["data"]

<?php

$response = Http::withToken('mk_live_YOUR_API_KEY')
    ->post('https://app.mailyte.com/api/v1/contacts/import', [
    'list_id' => '01JBT8XQ2M9WYC3K4F6R7S8T9V',
    'contacts' => [
        [
            'email' => 'ada@example.com',
            'name' => 'Ada Obi',
        ],
        [
            'email' => 'tunde@example.com',
            'name' => 'Tunde Bello',
            'attributes' => [
                'city' => 'Lagos',
                'plan' => 'pro',
            ],
        ],
    ],
]);

$data = $response->json('data');

require "net/http"
require "json"
uri = URI("https://app.mailyte.com/api/v1/contacts/import")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer mk_live_YOUR_API_KEY"
request["Content-Type"] = "application/json"
request.body = {
  "list_id": "01JBT8XQ2M9WYC3K4F6R7S8T9V",
  "contacts": [
    {
      "email": "ada@example.com",
      "name": "Ada Obi"
    },
    {
      "email": "tunde@example.com",
      "name": "Tunde Bello",
      "attributes": {
        "city": "Lagos",
        "plan": "pro"
      }
    }
  ]
}.to_json
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }

Response

Success.

• dataobject

  The counters always sum: imported + skipped_invalid + skipped_duplicate + skipped_over_plan == total.

  • objectstringcontact_import
  • totalinteger

    Rows we were given. For a CSV this is DATA rows — a recognised header row is not counted.

  • importedinteger

    Rows that became new contacts.

  • skipped_invalidinteger

    Rows skipped because the address was missing or invalid, or a required field was empty. Other rows still import.

  • skipped_duplicateinteger

    Addresses you already have, plus repeats in the file. Existing contacts are left as they are, so re-importing never re-subscribes anyone who unsubscribed.

  • skipped_over_planinteger

    Rows past the subscribed contacts your Marketing plan holds. The rows that fit are imported; plan_limit names the plan that takes the rest.

  • error_countinteger

    How many rows failed in total. Equal to skipped_invalid + skipped_duplicate + skipped_over_plan, and the number to trust — errors below is capped, so a file where everything failed reports 4,000 here and lists 100.

  • errorsarray<object>

    The rows that failed, in file order, up to 100. error_count gives the full number. [] means every row was accepted.

    • rowinteger

      1-based, counting DATA rows, so it lines up with your spreadsheet after the header.

    • emailstring

      The address exactly as you sent it, before normalising — empty when the row had none.

    • reasonstringmissing_email | invalid_email | duplicate_in_file | already_exists | missing_required_field | over_plan

      Why the row failed. duplicate_in_file: the address appears twice in your file. already_exists: you already have this contact. missing_required_field: a required contact field is empty, and message names it.

    • messagestring

      The same thing in words, safe to show a person. For a duplicate it names the earlier row.

  • plan_limitobject

    Null unless rows were stopped by your plan. Then the same context a 402 carries: limit_type, limit, current, suggested_product, cta_label and upgrade_url.

  • listobject

    The list named by list_id, with how many of the file's contacts joined it (new ones and ones you already had). Null when no list was given.

    • idstring
    • addedinteger

Returned inside the standard envelope.

Errors

Every status, with what causes it and what to do, is on the error reference.