Get subscription by email OAuth Scope: subscriptions:read

GET

https://api.beehiiv.com/v2/publications/:publicationId/subscriptions/by_email/:email

GET

/v2/publications/:publicationId/subscriptions/by_email/:email

curl https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/subscriptions/by_email/work%40example.com \
     -H "Authorization: Bearer <token>"

{
  "data": {
    "id": "sub_00000000-0000-0000-0000-000000000000",
    "email": "[email protected]",
    "status": "validating",
    "created": 1666800076,
    "subscription_tier": "free",
    "subscription_premium_tier_names": [
      "Premium",
      "Gold"
    ],
    "utm_source": "Twitter",
    "utm_medium": "organic",
    "utm_channel": "website",
    "utm_campaign": "utm_campaign",
    "utm_term": "",
    "utm_content": "",
    "referring_site": "https://www.blog.com",
    "referral_code": "referral_code",
    "subscription_premium_tiers": [
      {
        "id": "tier_00000000-0000-0000-0000-000000000000",
        "name": "name",
        "status": "active"
      }
    ],
    "custom_fields": [
      {}
    ],
    "tags": [
      "Premium",
      "Basic",
      "Active",
      "Engaged"
    ],
    "stats": {
      "emails_received": 25,
      "open_rate": 60.1,
      "click_through_rate": 25
    }
  }
}

Please note that this endpoint requires the email to be URL encoded. Please reference your language’s documentation for the correct method of encoding.

Retrieve a single subscription belonging to a specific email address in a specific publication.

<Info>Please note that this endpoint requires the email to be URL encoded. Please reference your language's documentation for the correct method of encoding.</Info> Retrieve a single subscription belonging to a specific email address in a specific publication.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

publicationIdstringRequiredformat: "^(pub_[0-9a-fA-F\-]+)$"

The prefixed ID of the publication object

emailstringRequired

The ID of the subscriber object

Query parameters

expand[]enumOptional

Optional list of expandable objects.
subscription_premium_tiers - Returns an array of tiers the subscription is associated with.
referrals - Returns an array of subscriptions with limited data - id, email, and status. These are the subscriptions that were referred by this subscription.
stats - Returns statistics about the subscription(s).
custom_fields - Returns an array of custom field values that have been set on the subscription.
tags - Returns an array of tags that have been set on the subscription.
newsletter_lists - Returns an array of newsletter list prefixed IDs the subscription is actively subscribed to.

Optional list of expandable objects. `subscription_premium_tiers ` - Returns an array of tiers the subscription is associated with. `referrals` - Returns an array of subscriptions with limited data - `id`, `email`, and `status`. These are the subscriptions that were referred by this subscription. `stats` - Returns statistics about the subscription(s). `custom_fields` - Returns an array of custom field values that have been set on the subscription. `tags` - Returns an array of tags that have been set on the subscription. `newsletter_lists` - Returns an array of newsletter list prefixed IDs the subscription is actively subscribed to.

Allowed values:

Response

dataobject

The subscription object

warningslist of objectsOptional

Present when custom field data in the request could not be applied (an unknown or missing field name). The subscription is still created or updated; any unresolvable custom field values are dropped rather than the whole request failing.

Errors

400

Bad Request Error

401

Unauthorized Error

404

Not Found Error

429

Too Many Requests Error

500

Internal Server Error