« Back to Documentation Overview


Section: Contacts
Version: 1.5.0

Add contact to the list.

  • campaign (mandatory) – CAMPAIGN_ID obtained from get_campaigns.
  • name (optional) – Name value.
  • email (mandatory) – Email value.
  • cycle_day (optional) – Insert contact on a given day at the autoresponder cycle. Value of 0 means the beginning of the cycle. Lack of this param means that a contact will not be inserted into cycle.
  • ip (optional) – Contact’s IP address used for geo location. Must be IPv4 in dotted decimal notation (like, IPv6 in full octet notation (like 0001:0002:0000:0000:0000:0000:0007:0008) or IPv6 in short octet notation (1:2:0:0:0:0:7:8). IPv6 compressed notation (1:2::7:8) is not allowed.
  • customs (optional) – List of contact customs. In case of contact update new customs will be inserted and the existing ones will be updated with the new values. Customs not provided on this list will not be removed. Custom name must be composed using up to 32: lowercase a-z letters, digits or underscores. Custom content maximum length is 255 characters.
Warning: Adding contact is not an instant action. It will appear on your list after validation or after validation and confirmation (in case of double-optin procedure). You can set subscribe callback to be notified about successful adding.
Warning: To update existing contact use methods such as set_contact_name, set_contact_customs or set_contact_cycle. Old param action is deprecated and ignored.
Warning: Optin setting is locked to double optin by default - confirmation email will be sent to newly added contacts. If you want to add contacts already confirmed on your side please contact us using this form and provide us with your campaign name and the description of your business model. We will set single optin for this campaign after short verification.
Warning: If you use this method as a way to handle your registration form, then you need to remember that this method does not allow to resubscribe a contact that was unsubscribed via a link, and also it is impossible to resend confirmation email using this kind of form.

Return Value

Example Request JSON

        "campaign": "CAMPAIGN_ID",
        "name": "name_value",
        "email": "email_value",
        "cycle_day": "cycle_day_value",
        "ip": "ip_value",
        "customs": [
                "name": "name_1_value",
                "content": "content_1_value"
                "name": "name_2_value",
                "content": "content_2_value"

Example Response JSON

    "queued": 1

Example Error Response JSON

    "code": -1,
    "message": "Contact already added to target campaign"
Method-specific Errors
Invalid email syntax
Missing campaign
Contact already queued for target campaign
Contact already added to target campaign
API-wide Errors
API key verification failed API key verification failed
API client IP not allowed API client IP not allowed
Invalid params Attribute params must be reference to hash