Sends

Get all sends#

The /api/sends endpoint lists all your sends.

$ MAILCOACH_TOKEN="your API token"
$ curl https://[[your-domain]].mailcoach.app/api/sends \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

This endpoint allows filtering by the following properties:

• subscriber_uuid
• campaign_uuid
• automation_mail_uuid
• transactional_mail_log_item_uuid

Sends are always sorted by -sent_at by default so the most recent sends are first, you can sort in the opposite direction using ?sort=sent_at.

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

{
    "data": [
        {
            "uuid": "e2cf1b63-6505-3d7a-9c51-a9eb67d97a48",
            "transport_message_id": null,
            "campaign_uuid": "caaec36d-b5b7-31ab-8f1a-9aff08f47045",
            "automation_mail_uuid": "9bbdca04-a68f-3bfd-b3c9-e2be829c5f23",
            "transactional_mail_log_item_uuid": "e3d8b659-cbad-36b9-bb4b-428f78a851be",
            "subscriber_uuid": "2051c60c-a9f3-31d0-a58c-7adcc32ea2e3",
            "sent_at": "2022-11-10T09:59:44.000000Z",
            "failed_at": null,
            "failure_reason": null,
            "open_count": null,
            "click_count": null,
            "created_at": "2022-11-10T09:58:44.000000Z",
            "updated_at": "2022-11-10T09:58:44.000000Z"
        },
        {
            "uuid": "fada1399-b540-3c3b-9d89-4f5e3656d437",
            "transport_message_id": null,
            "campaign_uuid": "7622cc9c-85c0-3e2e-991a-9064f02eca74",
            "automation_mail_uuid": "bcf75185-554e-3413-8028-f8e6032836e9",
            "transactional_mail_log_item_uuid": "93314af7-8921-3156-b92a-7ac0cb4c4552",
            "subscriber_uuid": "e9df76bc-3a11-3b3a-937d-0ab74df296ab",
            "sent_at": "2022-11-10T09:59:44.000000Z",
            "failed_at": null,
            "failure_reason": null,
            "open_count": null,
            "click_count": null,
            "created_at": "2022-11-10T09:58:44.000000Z",
            "updated_at": "2022-11-10T09:58:44.000000Z"
        },
        {
            "uuid": "5ea4b180-5cda-32ac-a529-0bcc57da0dec",
            "transport_message_id": null,
            "campaign_uuid": "23a9107f-a67a-300a-936a-50f7f91418eb",
            "automation_mail_uuid": "0e88d06f-e709-3421-ab43-e8059a9dd133",
            "transactional_mail_log_item_uuid": "9e0b0311-9c93-3450-9257-77172cb5ea8f",
            "subscriber_uuid": "50baf170-ed93-386e-b400-71f8afab713f",
            "sent_at": "2022-11-10T09:59:44.000000Z",
            "failed_at": null,
            "failure_reason": null,
            "open_count": null,
            "click_count": null,
            "created_at": "2022-11-10T09:58:44.000000Z",
            "updated_at": "2022-11-10T09:58:44.000000Z"
        }
    ],
    "links": {
        "first": "https://[[your-domain]].mailcoach.app/api/sends?page=1",
        "last": "https://[[your-domain]].mailcoach.app/api/sends?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "links": [
            {
                "url": null,
                "label": "« Previous",
                "active": false
            },
            {
                "url": "https://[[your-domain]].mailcoach.app/api/sends?page=1",
                "label": "1",
                "active": true
            },
            {
                "url": null,
                "label": "Next »",
                "active": false
            }
        ],
        "path": "https://[[your-domain]].mailcoach.app/api/sends",
        "per_page": 15,
        "to": 3,
        "total": 3
    }
}

Get a specific send#

If you don't want to retrieve all sends, you can get a specific send if you know its UUID.

$ MAILCOACH_TOKEN="your API token"
$ curl https://[[your-domain]].mailcoach.app/api/sends/e2cf1b63-6505-3d7a-9c51-a9eb67d97a48 \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

Response:

{
    "data": {
        "uuid": "e2cf1b63-6505-3d7a-9c51-a9eb67d97a48",
        "transport_message_id": null,
        "campaign_uuid": "caaec36d-b5b7-31ab-8f1a-9aff08f47045",
        "automation_mail_uuid": "9bbdca04-a68f-3bfd-b3c9-e2be829c5f23",
        "transactional_mail_log_item_uuid": "e3d8b659-cbad-36b9-bb4b-428f78a851be",
        "subscriber_uuid": "2051c60c-a9f3-31d0-a58c-7adcc32ea2e3",
        "sent_at": "2022-11-10T09:59:44.000000Z",
        "failed_at": null,
        "failure_reason": null,
        "open_count": null,
        "click_count": null,
        "created_at": "2022-11-10T09:58:44.000000Z",
        "updated_at": "2022-11-10T09:58:44.000000Z"
    }
}

Delete a send#

To delete a send, create a DELETE call to the /api/sends/<uuid> endpoint.

$ MAILCOACH_TOKEN="your API token"
$ curl -X DELETE https://[[your-domain]].mailcoach.app/api/sends/e2cf1b63-6505-3d7a-9c51-a9eb67d97a48 \
    -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": "Unauthorized."
}