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

Authenticate requests to this API's endpoints by sending 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
Request sample: 
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"
Response sample:
{
    "newsletter_id": 3666,
    "title": "Vitae placeat ratione esse omnis aliquid facilis ut quia.",
    "author": "نجاة حارث مامون السالم",
    "description": "Qui a doloribus hic porro quasi omnis rerum provident.",
    "image": "https://gohodhod.com/images/img-avatar-newsletter.png",
    "primary_color": "#13b981",
    "slug": "akram47",
    "profile_url": "https://gohodhod.com/@akram47",
    "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

Request sample: 
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\": \"Libero quis eum corporis eius et.\",
    \"primary_color\": \"#146ec2\",
    \"slug\": \"eum\"
}"

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

Request sample: 
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/phpHstUJ0"
Response sample:
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"

Request sample: 
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"
Response sample:
{
    "data": [
        {
            "id": 7798,
            "subject": "Optio tenetur autem quam et velit et quibusdam aut.",
            "number": 1,
            "description": null,
            "created_at": "2024-08-12T06:07:14.000000Z",
            "updated_at": "2024-08-12T06:07:14.000000Z",
            "published_at": "2024-08-14T06:07:14.000000Z",
            "is_published": false,
            "is_scheduled": true
        },
        {
            "id": 7799,
            "subject": "Iure facilis aliquam dicta cupiditate.",
            "number": 2,
            "description": null,
            "created_at": "2024-08-12T06:07:14.000000Z",
            "updated_at": "2024-08-12T06:07:14.000000Z",
            "published_at": "2024-08-12T06:07:14.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
Request sample: 
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"
Response sample:
{
    "id": 7800,
    "subject": "Iusto quis accusantium expedita ut consequatur sit.",
    "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      Iusto quis accusantium expedita ut consequatur sit.\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>بواسطة Nadhem</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/@engnadhem1191/issues/7800\" 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-08-12T06:07:14.000000Z",
    "updated_at": "2024-08-12T06:07:14.000000Z",
    "published_at": "2024-08-12T06:07:14.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
Request sample: 
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"
Response sample:
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
Request sample: 
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"
Response sample:
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
Request sample: 
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"
Response sample:
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
Request sample: 
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"
Response sample:
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"

Request sample: 
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"
Response sample:
{
    "data": [
        {
            "id": 679526,
            "email": "[email protected]",
            "first_name": "آناء",
            "last_name": "العرفج",
            "source": "dashboard",
            "created_at": "2024-08-12T06:07:14.000000Z",
            "updated_at": "2024-08-12T06:07:14.000000Z",
            "unsubscribed_at": "2024-08-12T06:07:14.815332Z",
            "suppressed_at": "2024-08-12T06:07:14.815351Z"
        },
        {
            "id": 679527,
            "email": "[email protected]",
            "first_name": "شرحبيل",
            "last_name": "المشيقح",
            "source": "import",
            "created_at": "2024-08-12T06:07:14.000000Z",
            "updated_at": "2024-08-12T06:07:14.000000Z",
            "unsubscribed_at": null,
            "suppressed_at": "2024-08-12T06:07:14.827381Z"
        }
    ],
    "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

Request sample: 
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\": \"eos\",
    \"last_name\": \"iste\",
    \"source\": \"non\",
    \"unsubscribed_at\": \"2024-08-12T06:07:14\",
    \"suppressed_at\": \"2024-08-12T06:07:14\"
}"
Response sample:
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
Request sample: 
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"
Response sample:
{
    "id": 679528,
    "email": "[email protected]",
    "first_name": "نجود",
    "last_name": "الجريد",
    "source": "embed",
    "created_at": "2024-08-12T06:07:14.000000Z",
    "updated_at": "2024-08-12T06:07:14.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

Request sample: 
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\": \"voluptas\",
    \"last_name\": \"ut\",
    \"source\": \"ratione\",
    \"unsubscribed_at\": \"2024-08-12T06:07:14\",
    \"suppressed_at\": \"2024-08-12T06:07:14\"
}"
Response sample:
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
Request sample: 
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"
Response sample:
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
Request sample: 
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"
Response sample:
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
Request sample: 
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"
Response sample:
true