Hodhod Api V1 - Beta

Postman collection → OpenAPI spec →

Introduction

This documentation aims to provide all the information you need to work with our API.

Authenticating requests

To authenticate requests, include an Authorization header with the value "Bearer {YOUR_AUTH_KEY}".

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

You can retrieve your token by visiting your dashboard and clicking Generate API token.

Newsletter

Returns profile info for the newsletter.

GET
https://gohodhod.com
/api/v1/newsletter/profile-info
requires authentication

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}
Content-Type
Example:
application/json
Accept
Example:
application/json
Example request: 
curl --request GET \
    --get "https://gohodhod.com/api/v1/newsletter/profile-info" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "newsletter_id": 4205,
    "title": "Aut vel laborum sint dolores.",
    "author": "علياء العمرو",
    "description": "Eius autem eveniet tempore iusto dicta ut consectetur neque illo illum commodi quae.",
    "image": "https://gohodhod.com/images/img-avatar-newsletter.png",
    "primary_color": "#13b981",
    "slug": "qobaisi",
    "profile_url": "https://gohodhod.com/@qobaisi",
    "externa_links": null
}

Update profile info for the newsletter.

PATCH
https://gohodhod.com
/api/v1/newsletter/profile-info
requires authentication

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}
Content-Type
Example:
application/json
Accept
Example:
application/json

Body Parameters

Example request: 
curl --request PATCH \
    "https://gohodhod.com/api/v1/newsletter/profile-info" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"title\": \"نشرة هدهد البريدية\",
    \"author\": \"عماد الدين\",
    \"description\": \"Amet voluptatum quam repellat et unde maxime et.\",
    \"primary_color\": \"#146ec2\",
    \"slug\": \"omnis\"
}"

Update newsletter's profile image.

POST
https://gohodhod.com
/api/v1/newsletter/profile-image
requires authentication

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}
Content-Type
Example:
multipart/form-data
Accept
Example:
application/json

Body Parameters

Example request: 
curl --request POST \
    "https://gohodhod.com/api/v1/newsletter/profile-image" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: multipart/form-data" \
    --header "Accept: application/json" \
    --form "image=@/tmp/phprHaIQj"
Example response:
true

Issues

Fetch a listing of the newsletter's issues.

GET
https://gohodhod.com
/api/v1/issues
requires authentication

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}
Content-Type
Example:
application/json
Accept
Example:
application/json

Query Parameters

status
string

(optional) Filters issue based on status. Can only be: "draft", "published" or "scheduled"

Example request: 
curl --request GET \
    --get "https://gohodhod.com/api/v1/issues" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "data": [
        {
            "id": 8768,
            "subject": "Error consequatur et sed nostrum.",
            "number": 1,
            "description": null,
            "created_at": "2024-10-28T09:19:08.000000Z",
            "updated_at": "2024-10-28T09:19:08.000000Z",
            "published_at": "2024-10-30T09:19:08.000000Z",
            "is_published": false,
            "is_scheduled": true
        },
        {
            "id": 8769,
            "subject": "Ea quo laboriosam exercitationem.",
            "number": 1,
            "description": null,
            "created_at": "2024-10-28T09:19:08.000000Z",
            "updated_at": "2024-10-28T09:19:08.000000Z",
            "published_at": "2024-10-28T09:19:08.000000Z",
            "is_published": true,
            "is_scheduled": false
        }
    ],
    "links": {
        "first": "/?page=1",
        "last": null,
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "path": "/",
        "per_page": "50",
        "to": 2
    }
}

Fetch the specified issue.

GET
https://gohodhod.com
/api/v1/issues/{issue_id}
requires authentication

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}
Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

issue_id
integer
required

The ID of the issue.

Example:
3
Example request: 
curl --request GET \
    --get "https://gohodhod.com/api/v1/issues/3" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "id": 8770,
    "subject": "In omnis possimus est nam suscipit laborum pariatur.",
    "number": 1,
    "description": null,
    "html_content": "<!-- Main table -->\n<table dir=\"rtl\" margin=\"0\" border=\"0\" cellspacing=\"0\" cellpadding=\"0\" align=\"center\" width=\"100%\">\n  <tbody>\n    <tr>\n  <td align=\"center\">\n    <h1\n      style=\"font-family: inherit; font-weight:bold; font-size:30px; color:#18181B; padding:0; padding-bottom: 0px; margin:0;\">\n      In omnis possimus est nam suscipit laborum pariatur.\n    </h1>\n  </td>\n</tr>\n<tr>\n  <td height=\"5\"></td>\n</tr>\n<tr>\n  <td align=\"center\"\n    style=\"font-family: inherit; font-size:14px; font-weight:bold; color: #13b981\">\n          <span>بواسطة لجين وريدة</span>\n      <span style=\"padding: 0 5px;\">•</span>\n        <span>#العدد 1</span>\n    <span style=\"padding: 0 5px;\">•</span>\n    <a href=\"http://gohodhod.com/@hafssa.wadih.1422/issues/8770\" style=\"color: #13b981\" target=\"_blank\">\n      عرض في المتصفح\n    </a>\n  </td>\n</tr>\n\n\n<tr>\n  <td height=\"20\"></td>\n</tr>\n<tr>\n  <td align=\"center\">\n    <hr style=\"height: 3px; width:75px; background-color:#d4d4d8; border: 0; border-radius: 100px;\">\n  </td>\n</tr>\n<tr>\n  <td height=\"20\"></td>\n</tr>\n\n  </tbody>\n</table>\n",
    "created_at": "2024-10-28T09:19:08.000000Z",
    "updated_at": "2024-10-28T09:19:08.000000Z",
    "published_at": "2024-10-28T09:19:08.000000Z",
    "is_published": true,
    "is_scheduled": false
}

Remove the specified issue from storage.

DELETE
https://gohodhod.com
/api/v1/issues/{issue_id}
requires authentication

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}
Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

issue_id
integer
required

The ID of the issue.

Example:
3
Example request: 
curl --request DELETE \
    "https://gohodhod.com/api/v1/issues/3" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
true

Publish the specified issue immediatly.

POST
https://gohodhod.com
/api/v1/issues/{issue_id}/publish
requires authentication

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}
Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

issue_id
integer
required

The ID of the issue.

Example:
3
Example request: 
curl --request POST \
    "https://gohodhod.com/api/v1/issues/3/publish" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
true

Schedue the specified issue for publish.

POST
https://gohodhod.com
/api/v1/issues/{issue_id}/schedule
requires authentication

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}
Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

issue_id
integer
required

The ID of the issue.

Example:
3

Query Parameters

published_at
string
required

The date and time when the issue should be published. Should be a valid datetime string and in the future (after current datetime).

Example:
2023-01-01 00:00:00
Example request: 
curl --request POST \
    "https://gohodhod.com/api/v1/issues/3/schedule?published_at=2023-01-01+00%3A00%3A00" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
true

Cancel scheduling for the specified issue.

POST
https://gohodhod.com
/api/v1/issues/{issue_id}/cancel-schedule
requires authentication

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}
Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

issue_id
integer
required

The ID of the issue.

Example:
3
Example request: 
curl --request POST \
    "https://gohodhod.com/api/v1/issues/3/cancel-schedule" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
true

Subscribers

Fetch a listing of newsletter's subscribers.

GET
https://gohodhod.com
/api/v1/subscribers
requires authentication

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}
Content-Type
Example:
application/json
Accept
Example:
application/json

Query Parameters

status
string

(optional) Filters subscribers based on status. Can only be: "subscribed", "unsubscribed" or "supressed"

Example request: 
curl --request GET \
    --get "https://gohodhod.com/api/v1/subscribers" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "data": [
        {
            "id": 721583,
            "email": "[email protected]",
            "first_name": "فايزة",
            "last_name": "باشا",
            "source": "dashboard",
            "created_at": "2024-10-28T09:19:08.000000Z",
            "updated_at": "2024-10-28T09:19:08.000000Z",
            "unsubscribed_at": null,
            "suppressed_at": "2024-10-28 09:19:08"
        },
        {
            "id": 721584,
            "email": "[email protected]",
            "first_name": "عبد الرحمن",
            "last_name": "باشا",
            "source": "import",
            "created_at": "2024-10-28T09:19:08.000000Z",
            "updated_at": "2024-10-28T09:19:08.000000Z",
            "unsubscribed_at": "2024-10-28 09:19:08",
            "suppressed_at": null
        }
    ],
    "links": {
        "first": "/?page=1",
        "last": null,
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "path": "/",
        "per_page": "50",
        "to": 2
    }
}

Store a newly created subscriber in storage.

POST
https://gohodhod.com
/api/v1/subscribers
requires authentication

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}
Content-Type
Example:
application/json
Accept
Example:
application/json

Body Parameters

Example request: 
curl --request POST \
    "https://gohodhod.com/api/v1/subscribers" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"email\": \"[email protected]\",
    \"first_name\": \"nihil\",
    \"last_name\": \"consequatur\",
    \"source\": \"tempore\",
    \"unsubscribed_at\": \"2024-10-28T09:19:08\",
    \"suppressed_at\": \"2024-10-28T09:19:08\"
}"
Example response:
true

Fetch the specified subscriber.

GET
https://gohodhod.com
/api/v1/subscribers/{subscriber_id}
requires authentication

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}
Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

subscriber_id
integer
required

The ID of the subscriber.

Example:
1
Example request: 
curl --request GET \
    --get "https://gohodhod.com/api/v1/subscribers/1" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "id": 721585,
    "email": "[email protected]",
    "first_name": "معالي",
    "last_name": "العقل",
    "source": "dashboard",
    "created_at": "2024-10-28T09:19:08.000000Z",
    "updated_at": "2024-10-28T09:19:08.000000Z",
    "unsubscribed_at": null,
    "suppressed_at": null
}

Update the specified subscriber in storage.

PUT
PATCH
https://gohodhod.com
/api/v1/subscribers/{subscriber_id}
requires authentication

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}
Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

subscriber_id
integer
required

The ID of the subscriber.

Example:
1

Body Parameters

Example request: 
curl --request PUT \
    "https://gohodhod.com/api/v1/subscribers/1" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"email\": \"[email protected]\",
    \"first_name\": \"et\",
    \"last_name\": \"sapiente\",
    \"source\": \"delectus\",
    \"unsubscribed_at\": \"2024-10-28T09:19:08\",
    \"suppressed_at\": \"2024-10-28T09:19:08\"
}"
Example response:
true

Remove the specified subscriber from storage.

DELETE
https://gohodhod.com
/api/v1/subscribers/{subscriber_id}
requires authentication

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}
Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

subscriber_id
integer
required

The ID of the subscriber.

Example:
1
Example request: 
curl --request DELETE \
    "https://gohodhod.com/api/v1/subscribers/1" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
true

Unsubscribe the specified subscriber from the newsletter.

POST
https://gohodhod.com
/api/v1/subscribers/{subscriber_id}/unsubscribe
requires authentication

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}
Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

subscriber_id
integer
required

The ID of the subscriber.

Example:
1
Example request: 
curl --request POST \
    "https://gohodhod.com/api/v1/subscribers/1/unsubscribe" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
true

Resubscribe the specified subscriber to the newsletter.

POST
https://gohodhod.com
/api/v1/subscribers/{subscriber_id}/resubscribe
requires authentication

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}
Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

subscriber_id
integer
required

The ID of the subscriber.

Example:
1
Example request: 
curl --request POST \
    "https://gohodhod.com/api/v1/subscribers/1/resubscribe" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
true