Skip to content

Commit

Permalink
updating readme
Browse files Browse the repository at this point in the history
  • Loading branch information
bwebs committed May 3, 2024
1 parent 88090df commit 739d5bc
Showing 1 changed file with 32 additions and 39 deletions.
71 changes: 32 additions & 39 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,17 +11,17 @@ Install from PyPI

```shell
pip install trycourier
# or
# or
poetry add trycourier
```

Python 3.7 or later is required.

## Usage

Use the `Courier` class to access all of our endpoints.

```python
import os
import courier

from courier.client import Courier
Expand All @@ -35,25 +35,23 @@ response = client.send(
to=courier.UserRecipient(
email="marty_mcfly@email.com",
data={
name: "Marty",
"name": "Marty",
}
),
content=courier.ElementalContentSugar(
title="Back to the Future",
body="Oh my {{name}}, we need 1.21 Gigawatts!",
body="Oh my {name}, we need 1.21 Gigawatts!",
),
routing=courier.Routing(
method=courier.RoutingMethod.ALL,
channels=["email"]
)
routing=courier.Routing(method="all", channels=["inbox", "email"]),
)
)

print(response)
```

## Async Client
The SDK also exports an asynchronous client, `AsyncCourier`.

The SDK also exports an asynchronous client, `AsyncCourier`.

```python
import os
Expand All @@ -66,32 +64,30 @@ client = AsyncCourier(
authorization_token="YOUR_TOKEN" # Defaults to COURIER_AUTH_TOKEN
)

async def main() -> None:
async def main() -> None:
response = await client.send(
message=courier.ContentMessage(
to=courier.UserRecipient(
email="marty_mcfly@email.com",
data={
name: "Marty",
"name": "Marty",
}
),
content=courier.ElementalContentSugar(
title="Back to the Future",
body="Oh my {{name}}, we need 1.21 Gigawatts!",
body="Oh my {name}, we need 1.21 Gigawatts!",
),
routing=courier.Routing(
method=courier.RoutingMethod.ALL,
channels=["email"]
)
routing=courier.Routing(method="all", channels=["email", "inbox"]),
)
)

asyncio.run(main())
```

## Timeouts
By default, the client is configured to have a timeout of 60 seconds.
You can customize this value at client instantiation.

By default, the client is configured to have a timeout of 60 seconds.
You can customize this value at client instantiation.

```python
from courier.client import Courier
Expand All @@ -103,7 +99,8 @@ client = Courier(
```

## Handling Exceptions
All exceptions thrown by the SDK will sublcass [courier.ApiError](./src/courier/core/api_error.py).

All exceptions thrown by the SDK will subclass [courier.ApiError](./src/courier/core/api_error.py).

```python
import courier
Expand All @@ -112,25 +109,25 @@ from courier.core import ApiError

try:
courier.send(...)
except APIError as e:
except APIError as e:
# handle any api related error
```

## Idempotency Keys

For `POST` methods, you can supply an `idempotencyKey` in the config parameter to
ensure the idempotency of the API Call. We recommend that you use a `V4 UUID` for the key.
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.
For more info, see [Idempotent Requests](https://docs.courier.com/reference/idempotent-requests)
For `POST` methods, you can supply an `idempotencyKey` in the config parameter to
ensure the idempotency of the API Call. We recommend that you use a `V4 UUID` for the key.
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.
For more info, see [Idempotent Requests](https://docs.courier.com/reference/idempotent-requests)
in the Courier documentation.

```python
import courier

courier.send(
message={...},
idempotency_key"YOUR_KEY",
message={...},
idempotency_key"YOUR_KEY",
idempotency_expiration="YOUR_EXPIRATION")
```

Expand All @@ -140,27 +137,25 @@ courier.send(

```python
import courier

from courier import Courier
from courier.client import Courier

client = Courier(
authorization_token="YOUR_TOKEN")

response = client.send(
message=courier.TemplateMessage(
template="my-template",
to=courier.UserRecipient(email="foo@bar.com")
to=courier.UserRecipient(user_id="abc-123")
)
)
print(response.message_id)
print(response.request_id)
```

### UTM Metadata with Message

```python
import courier

from courier import Courier
from courier.client import Courier

client = Courier(
authorization_token="YOUR_TOKEN")
Expand All @@ -179,10 +174,7 @@ response = client.send(
]
),
to=courier.UserRecipient(email="foo@bar.com"),
routing=courier.Routing(
method=courier.RoutingMethod.SINGLE,
channels=["email"]
),
routing=courier.Routing(method="all", channels=["email"]),
metadata=courier.MessageMetadata(
utm=courier.Utm(source="python")
)
Expand All @@ -194,10 +186,11 @@ print(response.request_id)
## Advanced

### Overriding HTTP Client
You can override the httpx client to customize it for your use case. Some common usecases

You can override the httpx client to customize it for your use case. Some common usecases
include support for proxies and transports.

```python
```python
import httpx
from courier.client import Courier

Expand Down

0 comments on commit 739d5bc

Please sign in to comment.