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": 2269,
    "title": "Enim ut pariatur sapiente mollitia architecto ducimus et.",
    "author": "إباء السماري",
    "description": "Minima illum aut illo tenetur quo ipsam et et.",
    "image": "https://gohodhod.com/images/img-avatar-newsletter.png",
    "primary_color": "#13b981",
    "slug": "obaisi.sami",
    "profile_url": "https://gohodhod.com/@obaisi.sami",
    "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\": \"Et ad voluptates quis laboriosam.\",
    \"primary_color\": \"#146ec2\",
    \"slug\": \"labore\"
}"

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/phpz4Arbg"
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": 5197,
            "subject": "Qui placeat ullam fugit laboriosam laborum aut.",
            "number": 1,
            "description": null,
            "created_at": "2023-09-10T19:32:09.000000Z",
            "updated_at": "2023-09-10T19:32:09.000000Z",
            "published_at": "2023-09-10T19:32:09.000000Z",
            "is_published": true,
            "is_scheduled": false
        },
        {
            "id": 5198,
            "subject": "Qui enim molestiae doloremque non.",
            "number": 18,
            "description": null,
            "created_at": "2023-09-10T19:32:09.000000Z",
            "updated_at": "2023-09-10T19:32:09.000000Z",
            "published_at": "2023-09-12T19:32:09.000000Z",
            "is_published": false,
            "is_scheduled": true
        }
    ],
    "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": 5199,
    "subject": "Et quo voluptas mollitia quasi natus autem.",
    "number": 37,
    "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      Et quo voluptas mollitia quasi natus autem.\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: #253745\">\n          <span>بواسطة hala_salka</span>\n      <span style=\"padding: 0 5px;\">•</span>\n        <span>#العدد 37</span>\n    <span style=\"padding: 0 5px;\">•</span>\n    <a href=\"http://gohodhod.com/@halasalka/issues/5199\" style=\"color: #253745\" 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": "2023-09-10T19:32:09.000000Z",
    "updated_at": "2023-09-10T19:32:09.000000Z",
    "published_at": "2023-09-12T19:32:09.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
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": 485870,
            "email": "[email protected]",
            "first_name": "لونا",
            "last_name": "السماعيل",
            "source": "embed",
            "created_at": "2023-09-10T19:32:09.000000Z",
            "updated_at": "2023-09-10T19:32:09.000000Z",
            "unsubscribed_at": null,
            "suppressed_at": null
        },
        {
            "id": 485871,
            "email": "[email protected]",
            "first_name": "وسيم",
            "last_name": "السماري",
            "source": "import",
            "created_at": "2023-09-10T19:32:09.000000Z",
            "updated_at": "2023-09-10T19:32:09.000000Z",
            "unsubscribed_at": null,
            "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

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\": \"facilis\",
    \"last_name\": \"esse\",
    \"source\": \"facilis\",
    \"unsubscribed_at\": \"2023-09-10T19:32:09\",
    \"suppressed_at\": \"2023-09-10T19:32:09\"
}"
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": 485872,
    "email": "[email protected]",
    "first_name": "هزار",
    "last_name": "المنيف",
    "source": "import",
    "created_at": "2023-09-10T19:32:09.000000Z",
    "updated_at": "2023-09-10T19:32:09.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\": \"unde\",
    \"last_name\": \"non\",
    \"source\": \"eius\",
    \"unsubscribed_at\": \"2023-09-10T19:32:09\",
    \"suppressed_at\": \"2023-09-10T19:32:09\"
}"
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