trycourier 4.1.0

A Python Package for communicating with the Courier REST API.

trycourier

This Python Package helps you send notifications through Courier, the smartest way to design & deliver notifications. Design your notifications once using our drag & drop editor, then deliver to any channel through one API. Email, mobile push, SMS, Slack — you name it!

Installation

Install from PyPI using pip:

$ pip install trycourier

Python 3.5 or later is required.

Usage

Using Token Auth

from trycourier import Courier

client = Courier(auth_token="your-auth-token") #or set via COURIER_AUTH_TOKEN env var

resp = client.send(
    event="your-event-id",
    recipient="your-recipient-id",
    profile={
        "email": "[e-mail]",
        "phone_number": "555-867-5309"
    },
    data={
      "world": "Python!"
    }
)
print(resp['messageId'])

Using Basic Auth

from trycourier import Courier

client = Courier(username="your-username", password="your-password")

resp = client.send(
    event="your-event-id",
    recipient="your-recipient-id",
    profile={
        "email": "[e-mail]",
        "phone_number": "555-867-5309"
    },
    data={
      "world": "Python!"
    }
)
print(resp['messageId'])

Timeouts

As of v1.4.0, the timeout is defaulted to 5 seconds. This is configurable using the timeout parameter when creating a client. You can specify the time in seconds using a float value for both Connect and Read or use a tuple to set them for each individual one (Connect, Read).

client = Courier(auth_token="your-auth-token",
                 timeout=3.5)

client = Courier(auth_token="your-auth-token",
                 timeout=(3.2, 3.3))

Advanced Usage

from trycourier import Courier

client = Courier(auth_token="your-auth-token")

"""
Example: send a message to a recipient
"""
resp = client.send(
    event="your-event-id",
    recipient="your-recipient-id",
    profile={}, # optional
    brand="your-brand-id", # optional
    data={}, # optional
    preferences={}, # optional
    override={} # optional
)
print(resp['messageId'])

"""
Example: send a message to a list
"""
resp = client.lists.send(
  event="your-event-id",
  list="your.list.id",
  brand="your-brand-id", # optional
  data={}, # optional
  override={} # optional
)
print(resp['messageId'])

"""
Example: send a message to a list pattern
"""
resp = client.lists.send(
  event="your-event-id",
  pattern="your.list.*",
  brand="your-brand-id", # optional
  data={}, # optional
  override={} # optional
)
print(resp['messageId'])

"""
Example: create a recipient's profile
"""
resp = client.profiles.add(
  recipient_id,
  {
    "email":"[e-mail]",
    "name":"Example Name"
  }
)

"""
Example: replace or create a recipient's profile
"""
resp = client.profiles.replace(
  recipient_id,
  {
    "email": "[e-mail]"
  }
)
print(resp['status'])

"""
Example: merge or create a recipient's profile
"""
resp = client.profiles.merge(
  recipient_id,
  {
    "phone_number": "[phone]"
  }
)
print(resp['status'])

"""
Example: get the subscribed lists of a recipient
"""
resp = client.profiles.get_subscriptions(
  recipient_id,
  cursor #optional
)
print(resp)

"""
Example: edit the contents of a recipient's profile with a patch operation
(follows JSON Patch conventions: RFC 6902).
"""
resp = client.profiles.patch(
  recipient_id,
  [
    {
      "op": "add", #operation 1: add this email to profile
      "path": "/parent",
      "value": "[e-mail]"
    }
    {
      "op": "replace", #operation 2: update with new email
      "path": "/parent",
      "value": "[e-mail]"
    }
    {
      "op": "copy", #operation 3: copy that email to /emergency_contact
      "from": "/parent",
      "path": "/emergency_contact"
    }
    ...
  ]
)
print(resp)


"""
Example: get a recipient's profile
"""
resp = client.profiles.get(recipient_id)
print(resp)


"""
Example: fetch the statuses of messages you've previously sent.
"""
resp = client.messages.list(
  cursor="MTU4OTQ5NTI1ODY4NywxLTVlYmRjNWRhLTEwODZlYWFjMWRmMjEwMTNjM2I0ZjVhMA", # optional
  event="your-event-id", # optional
  list="your-list-id", #optional
  message_id="your-message-id", #optional
  notification=["message-status-1", "message-status-2",...], #optional
  recipient="recipient-id" # optional
)
print(resp)

"""
Example: fetch the status of a message you've previously sent
"""
resp = client.messages.get(message_id)
print(resp)

"""
Example: fetch the array of events of a message you've previously sent.
"""
resp = client.messages.get_history(
message_id="your-message-id",
type="list-type" #optional ("FILTERED", "RENDERED", "MAPPED", "PROFILE_LOADED")
)
print(resp)

"""
Example: fetch the list of events
"""
resp = client.get_events()
print(resp)

"""
Example: fetch a specific event by event ID
"""
resp = client.get_event(event_id)
print(resp)

"""
Example: create or replace an event
"""
resp = client.replace_event(
  event_id,
  notification_id="GRPVB5P0BHMEZSNY6TP2X7TQHEBF",
  type="notificaton" ## optional, defaults to notification
)
print(resp)

"""
Example: get all brands
"""
resp = client.get_brands(
  cursor="MTU4OTQ5NTI1ODY4NywxLTVlYmRjNWRhLTEwODZlYWFjMWRmMjEwMTNjM2I0ZjVhMA", # optional
)
print(resp)

"""
Example: get a specific brand
"""
resp = client.get_brand(brand_id)
print(resp)

"""
Example: create a brand
"""
resp = client.create_brand({
  name="My Brand",
  settings={
    "color": {
      "primary": "#0000FF",
      "secondary": "#FF0000",
      "tertiary": "#00FF00"
    }
  }
})
print resp

"""
Example: replace a brand
"""
resp = client.replace_brand(
  brand_id,
  name="My New Brand",
  settings={
    "color": {
      "primary": "#FF0000",
      "secondary": "#00FF00",
      "tertiary": "#0000FF"
    }
  }
)
print resp

"""
Example: delete a brand
"""
client.delete_brand(brand_id)

"""
Example: get all lists
"""
resp = client.lists.list(
  cursor="MTU4OTQ5NTI1ODY4NywxLTVlYmRjNWRhLTEwODZlYWFjMWRmMjEwMTNjM2I0ZjVhMA", # optional
)
print resp

"""
Example: get a specific list
"""
resp = client.lists.get(list_id)
print resp

"""
Example: create or replace a list
"""
client.lists.put(list_id, name="My List")

"""
Example: delete a list
"""
client.lists.delete(list_id)

"""
Example: restore a list
"""
client.lists.restore(list_id)

"""
Example: get a list's subscribptions
"""
resp = client.lists.get_subscriptions(list_id,
  cursor="MTU4OTQ5NTI1ODY4NywxLTVlYmRjNWRhLTEwODZlYWFjMWRmMjEwMTNjM2I0ZjVhMA", # optional
)
print resp

"""
Example: replace many recipients to a new or existing list
"""
client.lists.put_subscriptions(list_id, [
  "RECIPIENT_ID_1",
  "RECIPIENT_ID_2"
])

"""
Example: Example: subscribe single recipient to a new or existing list
"""
client.lists.subscribe(list_id, recipient_id)

"""
Example: unsubscribe recipient from list
"""
client.lists.unsubscribe(list_id, recipient_id)

"""
Example: get a recipient's subscribed lists
"""
resp = client.lists.find_by_recipient_id(recipient_id,
  cursor="MTU4OTQ5NTI1ODY4NywxLTVlYmRjNWRhLTEwODZlYWFjMWRmMjEwMTNjM2I0ZjVhMA", # optional
)
print resp

"""
Example: Invoke an ad-hoc automation
"""

resp = client.automations.invoke(
    automation={'steps': [{ 'action': 'send' }]},
    brand="your-brand-id", # optional
    data={}, # optional
    profile={}, # optional
    recipient="your-recipient-id", # optional
    template="your-notification-template-id" # optional
)
print(resp['runId'])

"""
Example: Invoke an automation template
"""
resp = client.automations.invoke_template(
    template_id="your-automation-template-id",
    brand="your-brand-id", # optional
    data={}, # optional
    profile={}, # optional
    recipient="your-recipient-id", # optional
    template="your-notification-template-id" # optional
)
print(resp['runId'])

"""
Bulk Processing:
"""

"""
Example: Create a bulk processing job
"""
resp = client.bulk.create_job(
    message={'event': 'foo'},
    idempotency_key='1234ABCD', # optional
    idempotency_expiration='expiration-date' # optional
)
print(resp['jobId'])

"""
Example: Ingest users into a bulk processing job
"""
resp = client.bulk.ingest_users(
    job_id='12345',
    users=[{ 'profile': { 'email': '[e-mail]' } }],
    idempotency_key='1234ABCD', # optional
    idempotency_expiration='expiration-date' # optional
)
print(resp)

"""
Example: Run a bulk processing job
"""
client.bulk.run_job(
    job_id='12345',
    idempotency_key='1234ABCD', # optional
    idempotency_expiration='expiration-date' # optional
)

"""
Example: Get bulk processing job
"""
resp = client.bulk.get_job('12345')
print(resp)

"""
Example: Get bulk processing job user details
"""
resp = client.bulk.get_job_users('12345', cursor='abc') # cursor is optional
print(resp)

Idempotency

For POST methods, you can supply an idempotency_key to ensure the idempotency of the API Call. We recommend that you use a V4 UUID for the key. By default, keys are eligible to be removed from the system after they're at least 24 hours old, and a new request is generated if a key is reused after the original has been removed.

Also, the expiration of an idempotency key can be altered by setting a idempotency_expiration header value. The value of this header can be either epoch milliseconds or an ISO-8601 formatted date string. The minimum value that can be set is 24 hours. The maximum value that can be set is 1 year.

import uuid
from datetime import datetime, timedelta
from trycourier import Courier

client = Courier()

idempotency_key = uuid.uuid4()
expiration = (datetime.now()+timedelta(days=7)).isoformat()

resp = client.send(
    event="your-event-id",
    recipient="your-recipient-id",
    profile={
        "email": "[e-mail]",
        "phone_number": "555-867-5309"
    },
    data={
      "world": "Python!"
    },
    idempotency_key=idempotency_key,
    idempotency_expiration=expiration
)
print(resp['messageId'])

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/trycourier/courier-python. See CONTRIBUTING.md for more info.

License

The package is available as open source under the terms of the MIT License.