Tags & Segments

Get all tags#

The /api/email-lists/<uuid>/tags endpoint lists all your email list's tags.

$ MAILCOACH_TOKEN="your API token"
$ curl https://[[your-mailcoach-instance-url]]/api/email-lists/a69075c6-ff5c-4b6a-b217-12026cb72e4f/tags \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

As a result, you get the details of all your tags:

{
    "data": [
        {
            "uuid": "38b9e5cf-d10f-4463-b74d-bf26495e9f5b",
            "name": "one",
            "email_list_uuid": "a69075c6-ff5c-4b6a-b217-12026cb72e4f",
            "created_at": "2023-02-22T15:11:13.000000Z",
            "updated_at": "2023-02-22T15:11:13.000000Z"
        },
        {
            "uuid": "159b0003-a651-4176-92de-7d996d7d1611",
            "name": "two",
            "email_list_uuid": "a69075c6-ff5c-4b6a-b217-12026cb72e4f",
            "created_at": "2023-02-22T15:11:14.000000Z",
            "updated_at": "2023-02-22T15:11:14.000000Z"
        },
        ...
    ],
    "links": {
        "first": "https://[[your-mailcoach-instance-url]]/api/email-lists/a69075c6-ff5c-4b6a-b217-12026cb72e4f/tags?page=1",
        "last": "https://[[your-mailcoach-instance-url]]/api/email-lists/a69075c6-ff5c-4b6a-b217-12026cb72e4f/tags?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https://[[your-mailcoach-instance-url]]/api/email-lists/a69075c6-ff5c-4b6a-b217-12026cb72e4f/tags",
        "per_page": 15,
        "to": 3,
        "total": 3
    }
}

Get a specific tag#

If you don't want to retrieve all tags, you can get a specific tag if you know its UUID. The example below will get the details of tag with UUID a69075c6-ff5c-4b6a-b217-12026cb72e4f.

$ MAILCOACH_TOKEN="your API token"
$ curl https://[[your-mailcoach-instance-url]]/api/email-lists/a69075c6-ff5c-4b6a-b217-12026cb72e4f/tags/38b9e5cf-d10f-4463-b74d-bf26495e9f5b \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

Response:

{
    "data": {
        "uuid": "38b9e5cf-d10f-4463-b74d-bf26495e9f5b",
        "name": "one",
        "email_list": {
            "uuid": "7413f633-2652-386d-9eae-25e589538a03",
            "name": "Another list",
            ...
        },
        "email_list_uuid": "7413f633-2652-386d-9eae-25e589538a03",
        "created_at": "2023-02-22T15:11:13.000000Z",
        "updated_at": "2023-02-22T15:11:13.000000Z"
    }
}

Add a tag#

To add a tag, create a POST call to the /api/email-lists/<uuid>/tags endpoint.

$ MAILCOACH_TOKEN="your API token"
$ curl -X POST https://[[your-mailcoach-instance-url]]/api/email-lists \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"name":"my-tag", "visible_in_preferences": false}'

The only required field is the name field.

If the API call succeeded, you'll be given output like this.

{
    "data": {
        "uuid": "38b9e5cf-d10f-4463-b74d-bf26495e9f5b",
        "name": "my-tag",
        ...
    }
}

Update a tag#

To update a tag create a PUT call to the /api/email-lists/<uuid>/tag/<uuid> endpoint. When updating you should pass all fields mentioned in the payload above.

$ MAILCOACH_TOKEN="your API token"
$ curl -X PUT https://[[your-mailcoach-instance-url]]/api/email-lists/38b9e5cf-d10f-4463-b74d-bf26495e9f5b/tags/ \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"name":"updated-tag", "visible_in_preferences": false}'

Required fields and validation are the same as the create endpoint.

Delete a tag#

To delete an email list, create a DELETE call to the /api/email-lists/<uuid>/tags/<uuid> endpoint. In the example below we're deleting the tag with uuid 38b9e5cf-d10f-4463-b74d-bf26495e9f5b.

$ MAILCOACH_TOKEN="your API token"
$ curl -X DELETE https://[[your-mailcoach-instance-url]]/api/email-lists/a69075c6-ff5c-4b6a-b217-12026cb72e4f/tags/38b9e5cf-d10f-4463-b74d-bf26495e9f5b \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

If the API call succeeded, you'll be given an empty response with a 204 status code.

Get all segments#

The /api/email-lists/<uuid>/segments endpoint lists all your email list's segments.

$ MAILCOACH_TOKEN="your API token"
$ curl https://[[your-mailcoach-instance-url]]/api/email-lists/a69075c6-ff5c-4b6a-b217-12026cb72e4f/segments \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

As a result, you get the details of all your segments:

{
    "data": [
        {
            "uuid": "4efdbe3c-25e2-46b0-b799-1e1b6b5c28e6",
            "name": "A segment",
            "email_list_uuid": "7413f633-2652-386d-9eae-25e589538a03",
            "all_positive_tags_required": false,
            "all_negative_tags_required": false,
            "positive_tags": [
                "one"
            ],
            "negative_tags": [
                "two"
            ],
            "created_at": "2023-02-22T15:10:56.000000Z",
            "updated_at": "2023-02-22T15:10:56.000000Z"
        },
        ...
    ],
    "links": {
        "first": "https://[[your-mailcoach-instance-url]]/api/email-lists/a69075c6-ff5c-4b6a-b217-12026cb72e4f/segments?page=1",
        "last": "https://[[your-mailcoach-instance-url]]/api/email-lists/a69075c6-ff5c-4b6a-b217-12026cb72e4f/segments?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https://[[your-mailcoach-instance-url]]/api/email-lists/a69075c6-ff5c-4b6a-b217-12026cb72e4f/segments",
        "per_page": 15,
        "to": 3,
        "total": 3
    }
}

Get a specific segment#

If you don't want to retrieve all segments, you can get a specific segment if you know its UUID. The example below will get the details of segment with UUID a69075c6-ff5c-4b6a-b217-12026cb72e4f.

$ MAILCOACH_TOKEN="your API token"
$ curl https://[[your-mailcoach-instance-url]]/api/email-lists/a69075c6-ff5c-4b6a-b217-12026cb72e4f/segments/38b9e5cf-d10f-4463-b74d-bf26495e9f5b \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

Response:

{
    "data": {
        "uuid": "4efdbe3c-25e2-46b0-b799-1e1b6b5c28e6",
        "name": "A segment",
        "email_list_uuid": "7413f633-2652-386d-9eae-25e589538a03",
        "all_positive_tags_required": false,
        "all_negative_tags_required": false,
        "positive_tags": [
            "one"
        ],
        "negative_tags": [
            "two"
        ],
        "created_at": "2023-02-22T15:10:56.000000Z",
        "updated_at": "2023-02-22T15:10:56.000000Z"
    }
}

Add a segment#

To add a segment, create a POST call to the /api/email-lists/<uuid>/segments endpoint.

$ MAILCOACH_TOKEN="your API token"
$ curl -X POST https://[[your-mailcoach-instance-url]]/api/email-lists \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"name":"my-segment", "all_positive_tags_required": false, "all_negative_tags_required": false, "positive_tags": ["one"]}'

The only required field is the name field.

Fields:

• name => required | string
• all_positive_tags_required => boolean
• all_negative_tags_required => boolean
• positive_tags => array of strings
• negative_tags => array of strings

If the API call succeeded, you'll be given output like this.

{
    "data": {
        "uuid": "38b9e5cf-d10f-4463-b74d-bf26495e9f5b",
        "name": "my-segment",
        ...
    }
}

Update a segment#

To update a segment create a PUT call to the /api/email-lists/<uuid>/segment/<uuid> endpoint. When updating you should pass all fields mentioned in the payload above.

$ MAILCOACH_TOKEN="your API token"
$ curl -X PUT https://[[your-mailcoach-instance-url]]/api/email-lists/38b9e5cf-d10f-4463-b74d-bf26495e9f5b/segments/ \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"name":"updated-segment", "all_positive_tags_required": false, "all_negative_tags_required": false, "positive_tags": ["one"]}'

Required fields and validation are the same as the create endpoint.

Delete a segment#

To delete an email list, create a DELETE call to the /api/email-lists/<uuid>/segments/<uuid> endpoint. In the example below we're deleting the segment with uuid 38b9e5cf-d10f-4463-b74d-bf26495e9f5b.

$ MAILCOACH_TOKEN="your API token"
$ curl -X DELETE https://[[your-mailcoach-instance-url]]/api/email-lists/a69075c6-ff5c-4b6a-b217-12026cb72e4f/segments/38b9e5cf-d10f-4463-b74d-bf26495e9f5b \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

If the API call succeeded, you'll be given an empty response with a 204 status code.

Error handling#

If an error occurred, you'll be given a non-HTTP/200 response code. The resulting payload might look like this.

{
  "message": "The given data was invalid.",
  "errors": {
    "name": [
      "The name field is required."
    ]
  }
}