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": 4444,
    "title": "Vero nam magnam minima.",
    "author": "عهد العنزي",
    "description": "Quia qui laudantium assumenda nobis optio omnis aut.",
    "image": "https://gohodhod.com/images/img-avatar-newsletter.png",
    "primary_color": "#13b981",
    "slug": "hamad.osama",
    "profile_url": "https://gohodhod.com/@hamad.osama",
    "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\": \"Reprehenderit laboriosam eum ducimus magnam vel aut.\",
    \"primary_color\": \"#146ec2\",
    \"slug\": \"et\"
}"

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/phpe0flTM"
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": 9355,
            "subject": "Eum ad minima tempora voluptatibus nihil.",
            "number": 1,
            "description": null,
            "created_at": "2024-12-02T12:58:17.000000Z",
            "updated_at": "2024-12-02T12:58:17.000000Z",
            "published_at": null,
            "is_published": false,
            "is_scheduled": false
        },
        {
            "id": 9356,
            "subject": "Atque in in dolorem dolorum nemo molestiae nostrum debitis.",
            "number": 3,
            "description": null,
            "created_at": "2024-12-02T12:58:17.000000Z",
            "updated_at": "2024-12-02T12:58:17.000000Z",
            "published_at": "2024-12-02T12:58:17.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": 9357,
    "subject": "Quia perferendis ut possimus.",
    "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      Quia perferendis ut possimus.\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    >\n          <span>بواسطة Bushra</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/@shatnawibushra21954/issues/9357\" 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<style>\n  .dark .article-dynamic-data span,\n  .dark .article-dynamic-data font {\n    color: #e1e1e1 !important;\n  }\n</style>",
    "created_at": "2024-12-02T12:58:17.000000Z",
    "updated_at": "2024-12-02T12:58:17.000000Z",
    "published_at": "2024-12-04T12:58:17.000000Z",
    "is_published": false,
    "is_scheduled": true
}

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": 753647,
            "email": "[email protected]",
            "first_name": "عبلة",
            "last_name": "الخالدي",
            "source": "import",
            "created_at": "2024-12-02T12:58:17.000000Z",
            "updated_at": "2024-12-02T12:58:17.000000Z",
            "unsubscribed_at": null,
            "suppressed_at": "2024-12-02 12:58:17"
        },
        {
            "id": 753648,
            "email": "[email protected]",
            "first_name": "عمار",
            "last_name": "الشهري",
            "source": "import",
            "created_at": "2024-12-02T12:58:17.000000Z",
            "updated_at": "2024-12-02T12:58:17.000000Z",
            "unsubscribed_at": "2024-12-02 12:58:17",
            "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\": \"facilis\",
    \"last_name\": \"dolorum\",
    \"source\": \"nisi\",
    \"unsubscribed_at\": \"2024-12-02T12:58:17\",
    \"suppressed_at\": \"2024-12-02T12:58:17\"
}"
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": 753649,
    "email": "[email protected]",
    "first_name": "مظهر",
    "last_name": "الفدا",
    "source": "embed",
    "created_at": "2024-12-02T12:58:17.000000Z",
    "updated_at": "2024-12-02T12:58:17.000000Z",
    "unsubscribed_at": "2024-12-02 12:58:17",
    "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\": \"asperiores\",
    \"last_name\": \"veritatis\",
    \"source\": \"asperiores\",
    \"unsubscribed_at\": \"2024-12-02T12:58:17\",
    \"suppressed_at\": \"2024-12-02T12:58:17\"
}"
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