Manage Contacts with the Activetrail API

Most people use the Activetrail API to manage contacts data. You can subscribe and manage individuals and sync metadata with your systems. In this guide, you’ll learn the basics of how to manage contacts via the API.

Before You Start

Before you begin, review Activetrail’s basic API calls, and make sure you’re comfortable making those basic calls.

Identify Subscribers

We identify your subscribers by the id or email lowercase so you can easily predict the API URL of a contact’s data.

For example, to get the user 1234 who has the email abc@123.com , you can get the list contacts from the /contacts end point with the email and get the id from the response or just add the id to the end point like this: /contacts/1234

Check Subscription Status

To see if an email address subscribed to your group, you’ll need your group ID and the email address.

For the address, abc@123.com, you’d make a GET request to /contacts/abc@123.com or you can use contact id as well - to /contacts/12345678.

If the call returns a 404 response, the contact does not exist. They may have been deleted, or they were never in your account at all.

If the call returns a 200 response, check the status field. You’ll see one of these labels in the status field.

  • Subscribed This address is ready to receive email. You can only send campaigns to ‘subscribed’ addresses.
  • Unsubscribed This address had removed himself from your account by clicking the unsubscribe link in one of the campaigns.
  • Bounced - This address bounced.
  • Blocked - the contact has blocked himself from your account (report spam / customer request - the contact had asked active trail to remove him from your account without clicking in unsubscribe).

check the is_do_not_mail field. You’ll see one of these labels in the status field.

  • True - This address won’t’ receive any email - you can change this at any point.
  • False - This address is ready to receive email.

check the is_optin field. You’ll see one of these labels in the status field.

  • True - This address requested to be added with double-opt-in and was confirmed.
  • False - This address requested to be added with double-opt-in but hasn’t confirmed their subscription yet.

Add a contact

To add someone to your group, send a POST request to the Contacts endpoint: http://webapi.mymarketing.co.il/api/contacts . The request body should be a JSON object who has the member information you want to add, with is_do_not_mail and any other required list fields. 

 {
  "campaign_id": 1,
  "is_trigger_events": true,
  "first_name": "sample string 2",
  "last_name": "sample string 3",
  "email": "sample string 4",
  "anniversary": "sample string 5",
  "birthday": "sample string 6",
  "city": "sample string 7",
  "encryptedext1": "sample string 8",
  "encryptedext2": "sample string 9",
  "encryptedext3": "sample string 10",
  "encryptedext4": "sample string 11",
  "ext1": "sample string 12",
  "ext2": "sample string 13",
  "ext3": "sample string 14",
  "ext4": "sample string 15",
  "ext5": "sample string 16",
  "ext6": "sample string 17",
  "fax": "sample string 18",
  "phone1": "sample string 19",
  "phone2": "sample string 20",
  "street": "sample string 21",
  "zip_code": "sample string 22",
  "is_do_not_mail": false	,
  “status” : “Unsubscribed”,
    “is_optin” : true
}

Subscriber Status

To add a subscriber, you must include the subscriber’s state in your JSON object.

  • Use subscribed to add an address right away.
  • Use pending to send a confirmation email.
  • Use unsubscribed or cleaned to archive unused addresses.

The unsubscribed option is useful if you import addresses from another service. When you add subscribers to the unsubscribed state, you’ll have a record of the subscriber, and we’ll prevent sends to that address in the future. That’s ideal for inactive or unsubscribed addresses, which can increase spam complaints if they’re accidentally added as subscribed.

Update a Contact

Use a PUT request to the contact’s endpoint to update a contact’s metadata. The body can be a JSON object with only the data you want to change. For example, to unsubscribe 123@abc.com, make a put request to http://webapi.mymarketing.co.il/api/contacts/123456 with this JSON object as the body: 

{
    "state": "unsubscribed"
}

You can include read-only fields like email_address with your PUT request, but they will be ignored.

Delete an Address

We don’t typically recommend deleting addresses from your account because it’s permanent and cannot be undone. It’s better to change its state to unsubscribed or cleaned.

If you want to delete an address anyway, along with all its statistics, make a DELETE call to that contact’s endpoint.

Create or Update a Contact

For jobs that regularly sync data from one system to Activetrail, you may need to create a new contact or update an existing subscriber’s address. Depending in data volume, there are two approaches you could take for address creation and updates.

  • If data is static and grows slowly, update the contact first, and only try to create a new contact if the update fails.
  • For large imports, we recommend that you create contacts first and only update if the creation fails.