Welcome to onesignal-python-api

Building with an AI agent or LLM? See AGENTS.md for an agent-oriented integration guide — authentication, calling conventions, idempotent retries, and the full API reference.

A powerful way to send personalized messages at scale and build effective customer engagement strategies. Learn more at onesignal.com

• API version: 5.14.0
• Package version: 5.14.0

Requirements

Python >=3.6

Installation

pip install onesignal-python-api

Configuration

Every SDK requires authentication via API keys. Two key types are available:

• REST API Key — required for most endpoints (sending notifications, managing users, etc.). Found in your app's 设置 > Keys & IDs.
• 组织 API Key — only required for organization-level endpoints like creating or listing apps. Found in 组织 设置.

Warning: Store your API keys in environment variables or a secrets manager. Never commit them to source control.

import onesignal
from onesignal.api import default_api

configuration = onesignal.Configuration(
    rest_api_key='YOUR_REST_API_KEY',
    organization_api_key='YOUR_ORGANIZATION_API_KEY',
)

with onesignal.ApiClient(configuration) as api_client:
    client = default_api.DefaultApi(api_client)

Send a push notification

notification = onesignal.Notification(
    app_id='YOUR_APP_ID',
    contents=onesignal.StringMap(en='Hello from OneSignal!'),
    headings=onesignal.StringMap(en='Push Notification'),
    included_segments=['Subscribed Users'],
)

response = client.create_notification(notification)
print('Notification ID:', response.id)

Send an email

notification = onesignal.Notification(
    app_id='YOUR_APP_ID',
    email_subject='Important Update',
    email_body='<h1>Hello!</h1><p>This is an HTML email.</p>',
    included_segments=['Subscribed Users'],
    channel_for_external_user_ids='email',
)

response = client.create_notification(notification)

Send an SMS

notification = onesignal.Notification(
    app_id='YOUR_APP_ID',
    contents=onesignal.StringMap(en='Your SMS message content here'),
    included_segments=['Subscribed Users'],
    channel_for_external_user_ids='sms',
    sms_from='+15551234567',
)

response = client.create_notification(notification)

Full API reference

The complete list of API endpoints and their parameters is available in the DefaultApi documentation.

For the underlying REST API, see the OneSignal API reference.