Skip to content
iResendlyDocs

Segments and contacts

Manage the contacts and segments you send broadcasts to.

12 endpoints

Contacts can belong to any number of segments. They're separate from iResendly Marketing's contacts. Plan limits: 1,000, 10,000 or 50,000 contacts and 1, 10 or 100 segments. A spam complaint unsubscribes the contact automatically.

Create a segment

POST/segments

Creates an empty segment.

Body
  • namestringrequired

    The segment's name.

POST/segments
curl -X POST 'https://api.iresendly.com/segments' \
  -H 'Authorization: Bearer irs_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Newsletter"
}'
Response
{
  "object": "segment",
  "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
  "name": "Newsletter"
}

Retrieve a segment

GET/segments/{id}

One segment with its contact count (unsubscribed contacts included).

Path parameters
  • idstringrequired

    The segment id.

GET/segments/{id}
curl -X GET 'https://api.iresendly.com/segments/{id}' \
  -H 'Authorization: Bearer irs_xxxxxxxxx'
Response
{
  "object": "segment",
  "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
  "name": "Newsletter",
  "contacts_count": 1204
}

List segments

GET/segments

Every segment with its contact count.

GET/segments
curl -X GET 'https://api.iresendly.com/segments' \
  -H 'Authorization: Bearer irs_xxxxxxxxx'
Response
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "segment",
      "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
      "name": "Newsletter",
      "contacts_count": 1204
    }
  ]
}

List a segment's contacts

GET/segments/{id}/contacts

The contacts in one segment.

Path parameters
  • idstringrequired

    The segment id.

Query parameters
  • limitnumber

    Results per page, 1–100. Default 20.

  • afterstring

    Return results after this id (next page).

  • beforestring

    Return results before this id (previous page). Don't send with after.

GET/segments/{id}/contacts
curl -X GET 'https://api.iresendly.com/segments/{id}/contacts' \
  -H 'Authorization: Bearer irs_xxxxxxxxx'
Response
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "contact",
      "id": "479e3145-dd38-476b-932c-529ceb705947",
      "email": "steve@example.com"
    }
  ]
}

Delete a segment

DELETE/segments/{id}

Deletes the segment. Its contacts are kept.

Path parameters
  • idstringrequired

    The segment id.

DELETE/segments/{id}
curl -X DELETE 'https://api.iresendly.com/segments/{id}' \
  -H 'Authorization: Bearer irs_xxxxxxxxx'
Response
{
  "object": "segment",
  "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
  "deleted": true
}

Create a contact

POST/contacts

Creates the contact, or, if the email already exists, updates it and adds the segments.

Body
  • emailstringrequired

    The contact's address.

  • first_name · last_namestring

    Used by {{{FIRST_NAME}}} and {{{LAST_NAME}}}.

  • unsubscribedboolean

    Opted out of broadcasts.

  • propertiesobject

    Custom fields (string, number or null), usable as {{{key}}}. Updates merge into existing ones.

  • segments{ id }[]

    Segments to add the contact to.

POST/contacts
curl -X POST 'https://api.iresendly.com/contacts' \
  -H 'Authorization: Bearer irs_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "steve@example.com",
  "first_name": "Steve",
  "segments": [
    {
      "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf"
    }
  ]
}'
Response
{
  "object": "contact",
  "id": "479e3145-dd38-476b-932c-529ceb705947"
}

Retrieve a contact

GET/contacts/{id|email}

By id or by email address.

Path parameters
  • id|emailstringrequired

    The contact id or email.

GET/contacts/{id|email}
curl -X GET 'https://api.iresendly.com/contacts/{id|email}' \
  -H 'Authorization: Bearer irs_xxxxxxxxx'
Response
{
  "object": "contact",
  "id": "479e3145-dd38-476b-932c-529ceb705947",
  "email": "steve@example.com",
  "first_name": "Steve",
  "unsubscribed": false,
  "segments": [
    {
      "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf"
    }
  ]
}

List contacts

GET/contacts

All contacts, or one segment's with segment_id.

Query parameters
  • segment_idstring

    Only this segment's contacts.

  • limitnumber

    Results per page, 1–100. Default 20.

  • afterstring

    Return results after this id (next page).

  • beforestring

    Return results before this id (previous page). Don't send with after.

GET/contacts
curl -X GET 'https://api.iresendly.com/contacts' \
  -H 'Authorization: Bearer irs_xxxxxxxxx'
Response
{
  "object": "list",
  "has_more": false,
  "data": []
}

Update a contact

PATCH/contacts/{id|email}

Change names, properties or unsubscribed.

Path parameters
  • id|emailstringrequired

    The contact id or email.

PATCH/contacts/{id|email}
curl -X PATCH 'https://api.iresendly.com/contacts/{id|email}' \
  -H 'Authorization: Bearer irs_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
  "unsubscribed": true
}'
Response
{
  "object": "contact",
  "id": "479e3145-dd38-476b-932c-529ceb705947"
}

Add a contact to a segment

POST/contacts/{id|email}/segments/{segment_id}

Adds an existing contact to a segment.

Path parameters
  • id|emailstringrequired

    The contact id or email.

  • segment_idstringrequired

    The segment id.

POST/contacts/{id|email}/segments/{segment_id}
curl -X POST 'https://api.iresendly.com/contacts/{id|email}/segments/{segment_id}' \
  -H 'Authorization: Bearer irs_xxxxxxxxx'
Response
{
  "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf"
}

Remove a contact from a segment

DELETE/contacts/{id|email}/segments/{segment_id}

Takes the contact out of the segment. The contact itself is kept.

Path parameters
  • id|emailstringrequired

    The contact id or email.

  • segment_idstringrequired

    The segment id.

DELETE/contacts/{id|email}/segments/{segment_id}
curl -X DELETE 'https://api.iresendly.com/contacts/{id|email}/segments/{segment_id}' \
  -H 'Authorization: Bearer irs_xxxxxxxxx'
Response
{
  "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
  "deleted": true
}

Delete a contact

DELETE/contacts/{id|email}

Deletes the contact from every segment.

Path parameters
  • id|emailstringrequired

    The contact id or email.

DELETE/contacts/{id|email}
curl -X DELETE 'https://api.iresendly.com/contacts/{id|email}' \
  -H 'Authorization: Bearer irs_xxxxxxxxx'
Response
{
  "object": "contact",
  "contact": "479e3145-dd38-476b-932c-529ceb705947",
  "deleted": true
}
Still stuck? Write to us and we'll reply by email.Contact ussupport@iresendly.com