Main Interfaces¶
amcards.AMcardsClient¶
- class amcards.amcards.AMcardsClient(access_token: str, oauth_config: Optional[dict] = None, callback: Optional[Callable[[str, str, int], Any]] = None)¶
Bases:
object
Client for AMcards API.
- __init__(access_token: str, oauth_config: Optional[dict] = None, callback: Optional[Callable[[str, str, int], Any]] = None) None ¶
Client for AMcards API.
- Parameters:
access_token (str) – Your AMcards access token. Generate one here.
oauth_config (Optional[dict]) –
Your OAuth configuration, this is optional, but if you choose to include it, it must include all of the following keys:
{ 'refresh_token': 'yourrefreshtoken', 'expiration': 1671692131130, # Note that expiration is specified as a unix timestamp in ms. 'client_id': 'yourapplicationclientid', 'client_secret': 'yourapplicationclientsecret' }
callback (Optional[Callable[[str, str, int], Any]]) – This function will be called by the client when you have
oauth_config
defined, and the client refreshes theaccess_token
before making a request. This can be useful when you need perform some logic when the client refreshes the specifiedaccess_token
(like updating your database to reflect the new access_token and refresh_token).callback
is optional, but if you choose to include it, it needs to accept the following keyword arguments:access_token
refresh_token
expiration
.callback
will be called by the client as follows:callback(access_token='newaccesstoken', refresh_token='newrefreshtoken', expiration=1671692135130)
, note thatexpiration
is specified as a unix timestamp in ms.
- campaign(id: str | int) Campaign ¶
Fetches client’s AMcards drip campaign with a specified id.
- Parameters:
id (str or int) – Unique id for the
drip campaign
you are fetching.- Returns:
The client’s
drip campaign
with specifiedid
.- Return type:
- Raises:
ForbiddenCampaignError – When the drip campaign for the specified
id
either does not exist or is not owned by the client’s user.AuthenticationError – When the client’s
access_token
is invalid.
- campaigns(limit: int = 25, skip: int = 0) List[Campaign] ¶
Fetches client’s AMcards drip campaigns.
- Parameters:
limit (int) – Defaults to
25
. Max number of drip campaigns to be fetched.skip (int) – Defaults to
0
. Number of drip campaigns to be skipped.
- Returns:
The client’s
drip campaigns
.- Return type:
List[
Campaign
]- Raises:
AuthenticationError – When the client’s
access_token
is invalid.
- card(id: str | int) Card ¶
Fetches client’s AMcards card with a specified id.
- Parameters:
id (str or int) – Unique id for the
card
you are fetching.- Returns:
The client’s
card
with specifiedid
.- Return type:
- Raises:
ForbiddenCardError – When the card for the specified
id
either does not exist or is not owned by the client’s user.AuthenticationError – When the client’s
access_token
is invalid.
- cards(limit: int = 25, skip: int = 0, filters: Optional[dict] = None) List[Card] ¶
Fetches client’s AMcards cards.
- Parameters:
limit (int) – Defaults to
25
. Max number of cards to be fetched.skip (int) – Defaults to
0
. Number of cards to be skipped.filters (Optional[dict]) –
Defaults to
None
. Filters to be applied when fetching cards.A common use case is to use
filter = {'third_party_contact_id': 'some_target_id'}
, this will fetch all cards that were shipped to a recipient with athird_party_contact_id == 'some_target_id'
.
- Returns:
The client’s
cards
.- Return type:
List[
Card
]- Raises:
AuthenticationError – When the client’s
access_token
is invalid.
- contact(id: str | int) Contact ¶
Fetches client’s AMcards contact with a specified id.
- Parameters:
id (str or int) – Unique id for the
contact
you are fetching.- Returns:
The client’s
contact
with specifiedid
.- Return type:
- Raises:
ForbiddenContactError – When the contact for the specified
id
either does not exist or is not owned by the client’s user.AuthenticationError – When the client’s
access_token
is invalid.
- contacts(limit: int = 25, skip: int = 0, filters: Optional[dict] = None) List[Contact] ¶
Fetches client’s AMcards contacts.
- Parameters:
limit (int) – Defaults to
25
. Max number of contacts to be fetched.skip (int) – Defaults to
0
. Number of contacts to be skipped.filters (Optional[dict]) –
Defaults to
None
. Filters to be applied when fetching contacts.A common use case is to use
filter = {'last_name': 'Smith'}
, this will fetch all contacts withlast_name == 'Smith'
.
- Returns:
The client’s
contacts
.- Return type:
List[
Contact
]- Raises:
AuthenticationError – When the client’s
access_token
is invalid.
- create_contact(first_name: str, last_name: str, address_line_1: str, city: str, state: str, postal_code: str, country: Optional[str] = None, notes: Optional[str] = None, email: Optional[str] = None, organization: Optional[str] = None, phone: Optional[str] = None, birth_year: Optional[str] = None, birth_month: Optional[str] = None, birth_day: Optional[str] = None, anniversary_year: Optional[str] = None, anniversary_month: Optional[str] = None, anniversary_day: Optional[str] = None) None ¶
Creates a new contact for the client.
- Parameters:
first_name (str) – Contact’s first name.
last_name (str) – Contact’s last name.
address_line_1 (str) – Contact’s primary address line.
city (str) – Contact’s city.
state (str) – Contact’s state.
postal_code (str) – Contact’s postal code.
country (Optional[str]) – Contact’s country.
notes (Optional[str]) – Contact’s notes.
email (Optional[str]) – Contact’s email address.
organization (Optional[str]) – Contact’s organization.
phone (Optional[str]) – Contact’s phone number. In the form
"12223334444"
.birth_year (Optional[str]) – Contact’s birth year. In the form
"YYYY"
.birth_month (Optional[str]) – Contact’s birth month. In the form
"MM"
.birth_day (Optional[str]) – Contact’s birth day. In the form
"DD"
.anniverary_year (Optional[str]) – Contact’s anniversary year. In the form
"YYYY"
.anniverary_month (Optional[str]) – Contact’s anniversary month. In the form
"MM"
.anniverary_day (Optional[str]) – Contact’s anniversary day. In the form
"DD"
.
- Raises:
AMcardsException – When something unexpected occurs.
AuthenticationError – When the client’s
access_token
is invalid.
- delete_contact(id: str | int) None ¶
Deletes client’s AMcards contact with a specified id.
- Parameters:
id (str or int) – Unique id for the
contact
you are deleting.- Raises:
ForbiddenContactError – When the contact for the specified
id
either does not exist or is not owned by the client’s user.AuthenticationError – When the client’s
access_token
is invalid.
- mailing(id: str | int) Mailing ¶
Fetches client’s AMcards mailing with a specified id.
- Parameters:
id (str or int) – Unique id for the
mailing
you are fetching.- Returns:
The client’s
mailing
with specifiedid
.- Return type:
- Raises:
ForbiddenMailingError – When the mailing for the specified
id
either does not exist or is not owned by the client’s user.AuthenticationError – When the client’s
access_token
is invalid.
- quicksend(id: str | int) Template ¶
Fetches client’s AMcards quicksend template with a specified id.
- Parameters:
id (str or int) – Unique id for the
quicksend template
you are fetching.- Returns:
The client’s
quicksend template
with specifiedid
.- Return type:
- Raises:
ForbiddenTemplateError – When the quicksend template for the specified
id
either does not exist or is not owned by the client’s user.AuthenticationError – When the client’s
access_token
is invalid.
- quicksends(limit: int = 25, skip: int = 0) List[Template] ¶
Fetches client’s AMcards quicksend templates.
- Parameters:
limit (int) – Defaults to
25
. Max number of quicksend templates to be fetched.skip (int) – Defaults to
0
. Number of quicksend templates to be skipped.
- Returns:
The client’s
quicksend templates
.- Return type:
List[
Template
]- Raises:
AuthenticationError – When the client’s
access_token
is invalid.
- send_campaign(campaign_id: str | int, initiator: str, shipping_address: dict, return_address: Optional[dict] = None, send_date: Optional[str] = None) CampaignResponse ¶
Attempt to send a drip campaign.
>>> from amcards import AMcardsClient >>> client = AMcardsClient('youraccesstoken') >>> res = client.send_campaign( ... campaign_id='123', ... initiator='myintegration123', ... shipping_address={ ... 'first_name': 'Ralph', ... 'last_name': 'Mullins', ... 'address_line_1': '2285 Reppert Road', ... 'city': 'Southfield', ... 'state': 'MI', ... 'postal_code': '48075', ... 'country': 'US' ... } ... ) >>> res.card_ids [1528871, 1528872] >>> res.mailing_id 29693 >>> res.message 'Thanks! Your cards have been scheduled and $8.84 was debited from your credits.' >>> res.user_email 'example@example.com' >>> res.shipping_address {'country': 'US', 'state': 'MI', 'postal_code': '48075', 'first_name': 'Ralph', 'city': 'Southfield', 'address_line_1': '2285 Reppert Road', 'last_name': 'Mullins'}
- Parameters:
campaign_id (str or int) – Unique id for the
drip campaign
you are sending.initiator (str) – Unique identifier of client’s user so if multiple users use a single AMcards.com account, a drip campaign can be identified per person.
shipping_address (dict) –
Dict of shipping details. Here’s an example how the dict might look, make sure you include all of the required keys:
{ 'first_name': 'Ralph', 'last_name': 'Mullins', 'address_line_1': '2285 Reppert Road', 'city': 'Southfield', 'state': 'MI', 'postal_code': '48075', 'country': 'US', 'organization': 'Google', # OPTIONAL 'phone_number': '15556667777', # OPTIONAL 'birth_date': '2003-12-25', # OPTIONAL 'anniversary_date': '2022-10-31', # OPTIONAL 'third_party_contact_id': 'crmid1453131' # OPTIONAL }
return_address (Optional[dict]) –
Dict of return details that will override the client’s AMcards user default return details. Here’s an example how the dict might look, all of the keys are optional:
{ 'first_name': 'Ralph', # OPTIONAL 'last_name': 'Mullins', # OPTIONAL 'address_line_1': '2285 Reppert Road', # OPTIONAL 'city': 'Southfield', # OPTIONAL 'state': 'MI', # OPTIONAL 'postal_code': '48075', # OPTIONAL 'country': 'US', # OPTIONAL }
send_date (Optional[str]) – The date the drip campaign should be sent, in
"YYYY-MM-DD"
format. If not specified, the drip campaign will be scheduled for the following day.
- Returns:
AMcards’
response
for sending a single drip campaign.- Return type:
- Raises:
CampaignSendError – When something goes wrong when attempting to send a drip campaign.
AuthenticationError – When the client’s
access_token
is invalid.ForbiddenCampaignError – When the client does not own the
campaign
specified bycampaign_id
.ShippingAddressError – When
shipping_address
is missing some required keys.DateFormatError – When one of the dates provided is not in
"YYYY-MM-DD"
format.PhoneFormatError – When the
phone_number
is not a digit string of length 10.InsufficientCreditsError – When the client’s user has insufficient credits in their balance.
DuplicateCampaignError – When AMcards detects this
campaign
specified bycampaign_id
is a duplicate andsend_if_duplicate
inCampaign
isFalse
.
- send_campaign_cost(campaign_id: str | int, shipping_address: dict, return_address: Optional[dict] = None, send_date: Optional[str] = None) int ¶
Get cost for a campaign send. Without actually sending the campaign.
>>> from amcards import AMcardsClient >>> client = AMcardsClient('youraccesstoken') >>> res = client.send_campaign_cost( ... campaign_id='123', ... shipping_address={ ... 'first_name': 'Ralph', ... 'last_name': 'Mullins', ... 'address_line_1': '2285 Reppert Road', ... 'city': 'Southfield', ... 'state': 'MI', ... 'postal_code': '48075', ... 'country': 'US' ... } ... ) >>> res 442
- Parameters:
campaign_id (str or int) – Unique id for the
drip campaign
you are getting cost for.shipping_address (dict) –
Dict of shipping details. Here’s an example how the dict might look, make sure you include all of the required keys:
{ 'first_name': 'Ralph', 'last_name': 'Mullins', 'address_line_1': '2285 Reppert Road', 'city': 'Southfield', 'state': 'MI', 'postal_code': '48075', 'country': 'US', 'organization': 'Google', # OPTIONAL 'phone_number': '15556667777', # OPTIONAL 'birth_date': '2003-12-25', # OPTIONAL 'anniversary_date': '2022-10-31', # OPTIONAL 'third_party_contact_id': 'crmid1453131' # OPTIONAL }
return_address (Optional[dict]) –
Dict of return details that will override the client’s AMcards user default return details. Here’s an example how the dict might look, all of the keys are optional:
{ 'first_name': 'Ralph', # OPTIONAL 'last_name': 'Mullins', # OPTIONAL 'address_line_1': '2285 Reppert Road', # OPTIONAL 'city': 'Southfield', # OPTIONAL 'state': 'MI', # OPTIONAL 'postal_code': '48075', # OPTIONAL 'country': 'US', # OPTIONAL }
send_date (Optional[str]) – The date the drip campaign should be sent, in
"YYYY-MM-DD"
format. If not specified, the drip campaign will be scheduled for the following day.
- Returns:
Cost for sending campaign in cents.
- Return type:
int
- Raises:
AuthenticationError – When the client’s
access_token
is invalid.ForbiddenCampaignError – When the client does not own the
campaign
specified bycampaign_id
.ShippingAddressError – When
shipping_address
is missing some required keys.DateFormatError – When one of the dates provided is not in
"YYYY-MM-DD"
format.PhoneFormatError – When the
phone_number
is not a digit string of length 10.
- send_card(template_id: str | int, initiator: str, shipping_address: dict, return_address: Optional[dict] = None, send_date: Optional[str] = None, message: Optional[str] = None) CardResponse ¶
Attempt to send a card.
>>> from amcards import AMcardsClient >>> client = AMcardsClient('youraccesstoken') >>> res = client.send_card( ... template_id='123', ... initiator='myintegration123', ... shipping_address={ ... 'first_name': 'Ralph', ... 'last_name': 'Mullins', ... 'address_line_1': '2285 Reppert Road', ... 'city': 'Southfield', ... 'state': 'MI', ... 'postal_code': '48075', ... 'country': 'US' ... } ... ) >>> res.card_id 1522873 >>> res.total_cost 442 >>> res.message 'Card created successfully!' >>> res.user_email 'example@example.com' >>> res.shipping_address {'last_name': 'Mullins', 'address_line_1': '2285 Reppert Road', 'first_name': 'Ralph', 'country': 'US', 'state': 'MI', 'postal_code': '48075', 'city': 'Southfield'}
- Parameters:
template_id (str or int) – Unique id for the
template
you are sending.initiator (str) – Unique identifier of client’s user so if multiple users use a single AMcards.com account, a card can be identified per person.
shipping_address (dict) –
Dict of shipping details. Here’s an example how the dict might look, make sure you include all of the required keys:
{ 'first_name': 'Ralph', 'last_name': 'Mullins', 'address_line_1': '2285 Reppert Road', 'city': 'Southfield', 'state': 'MI', 'postal_code': '48075', 'country': 'US', 'organization': 'Google', # OPTIONAL 'third_party_contact_id': 'crmid1453131' # OPTIONAL }
return_address (Optional[dict]) –
Dict of return details that will override the client’s AMcards user default return details. Here’s an example how the dict might look, all of the keys are optional:
{ 'first_name': 'Ralph', # OPTIONAL 'last_name': 'Mullins', # OPTIONAL 'address_line_1': '2285 Reppert Road', # OPTIONAL 'city': 'Southfield', # OPTIONAL 'state': 'MI', # OPTIONAL 'postal_code': '48075', # OPTIONAL 'country': 'US', # OPTIONAL }
send_date (Optional[str]) – The date the card should be sent. If not specified, the card will be scheduled for the following day. The format should be:
"YYYY-MM-DD"
.message (Optional[str]) – A message to add to the card. This will be added to the inside bottom or inside right panel on the card and will not replace any message that is currently on the template.
- Returns:
AMcards’
response
for sending a single card.- Return type:
- Raises:
CardSendError – When something goes wrong when attempting to send a card.
AuthenticationError – When the client’s
access_token
is invalid.ForbiddenTemplateError – When the client does not own the
template
specified bytemplate_id
.ShippingAddressError – When
shipping_address
is missing some required keys.DateFormatError – When one of the dates provided is not in
"YYYY-MM-DD"
format.InsufficientCreditsError – When the client’s user has insufficient credits in their balance.
- send_card_cost(template_id: str | int, shipping_address: dict, return_address: Optional[dict] = None, send_date: Optional[str] = None) int ¶
Get cost for a card send. Without actually sending the card.
>>> from amcards import AMcardsClient >>> client = AMcardsClient('youraccesstoken') >>> res = client.send_card_cost( ... template_id='123', ... shipping_address={ ... 'first_name': 'Ralph', ... 'last_name': 'Mullins', ... 'address_line_1': '2285 Reppert Road', ... 'city': 'Southfield', ... 'state': 'MI', ... 'postal_code': '48075', ... 'country': 'US' ... } ... ) >>> res 442
- Parameters:
template_id (str or int) – Unique id for the
template
you are getting cost for.shipping_address (dict) –
Dict of shipping details. Here’s an example how the dict might look, make sure you include all of the required keys:
{ 'first_name': 'Ralph', 'last_name': 'Mullins', 'address_line_1': '2285 Reppert Road', 'city': 'Southfield', 'state': 'MI', 'postal_code': '48075', 'country': 'US', 'organization': 'Google', # OPTIONAL 'third_party_contact_id': 'crmid1453131' # OPTIONAL }
return_address (Optional[dict]) –
Dict of return details that will override the client’s AMcards user default return details. Here’s an example how the dict might look, all of the keys are optional:
{ 'first_name': 'Ralph', # OPTIONAL 'last_name': 'Mullins', # OPTIONAL 'address_line_1': '2285 Reppert Road', # OPTIONAL 'city': 'Southfield', # OPTIONAL 'state': 'MI', # OPTIONAL 'postal_code': '48075', # OPTIONAL 'country': 'US', # OPTIONAL }
send_date (Optional[str]) – The date the card should be sent. If not specified, the card will be scheduled for the following day. The format should be:
"YYYY-MM-DD"
.
- Returns:
Cost for sending card in cents.
- Return type:
int
- Raises:
AuthenticationError – When the client’s
access_token
is invalid.ForbiddenTemplateError – When the client does not own the
template
specified bytemplate_id
.ShippingAddressError – When
shipping_address
is missing some required keys.DateFormatError – When one of the dates provided is not in
"YYYY-MM-DD"
format.
- send_cards(template_id: str | int, initiator: str, shipping_addresses: List[dict], return_address: Optional[dict] = None, send_date: Optional[str] = None, send_if_error: bool = False) CardsResponse ¶
Attempt to send multiple cards.
>>> from amcards import AMcardsClient >>> client = AMcardsClient('youraccesstoken') >>> res = client.send_cards( ... template_id='123', ... initiator='myintegration123', ... shipping_addresses=[ ... { ... 'first_name': 'Ralph', ... 'last_name': 'Mullins', ... 'address_line_1': '2285 Reppert Road', ... 'city': 'Southfield', ... 'state': 'MI', ... 'postal_code': '48075', ... 'country': 'US', ... 'organization': 'Google', ... 'third_party_contact_id': 'crmid1453131' ... }, ... { ... 'first_name': 'Keith', ... 'last_name': 'May', ... 'address_line_1': '364 Spruce Drive', ... 'city': 'Philadelphia', ... 'state': 'PA', ... 'postal_code': '19107', ... 'country': 'US' ... } ... ] ... ) >>> res.mailing_id 29694 >>> res.message "You can check the mailing_uri. When the 'status' is '0' (aka Completed) you can then read the 'report' field for a list of cards that were created. See each card's 'status' to make sure that it was created. If the status is 'fail' there will be a 'message' stating the issue with that recipient." >>> res.user_email 'example@example.com' >>> res.shipping_addresses [{'country': 'US', 'state': 'MI', 'postal_code': '48075', 'first_name': 'Ralph', 'city': 'Southfield', 'address_line_1': '2285 Reppert Road', 'last_name': 'Mullins', 'organization': 'Google', 'third_party_contact_id': 'crmid1453131'}, {'country': 'US', 'state': 'PA', 'postal_code': '19107', 'first_name': 'Keith', 'city': 'Philadelphia', 'address_line_1': '364 Spruce Drive', 'last_name': 'May'}]
- Parameters:
template_id (str or int) – Unique id for the
template
you are sending.initiator (str) – Unique identifier of client’s user so if multiple users use a single AMcards.com account, a card can be identified per person.
shipping_addresses (List[dict]) –
List of shipping details. Here’s an example how the list might look, make sure you include all of the required keys for each dict in the list:
[ { 'first_name': 'Ralph', 'last_name': 'Mullins', 'address_line_1': '2285 Reppert Road', 'city': 'Southfield', 'state': 'MI', 'postal_code': '48075', 'country': 'US', 'organization': 'Google', # OPTIONAL 'third_party_contact_id': 'crmid1453131' # OPTIONAL }, { 'first_name': 'Keith', 'last_name': 'May', 'address_line_1': '364 Spruce Drive', 'city': 'Philadelphia', 'state': 'PA', 'postal_code': '19107', 'country': 'US' } ]
return_address (Optional[dict]) –
Dict of return details that will override the client’s AMcards user default return details. Here’s an example how the dict might look, all of the keys are optional:
{ 'first_name': 'Ralph', # OPTIONAL 'last_name': 'Mullins', # OPTIONAL 'address_line_1': '2285 Reppert Road', # OPTIONAL 'city': 'Southfield', # OPTIONAL 'state': 'MI', # OPTIONAL 'postal_code': '48075', # OPTIONAL 'country': 'US', # OPTIONAL }
send_date (Optional[str]) – The date the card should be sent, If not specified, the card will be scheduled for the following day. The format should be:
"YYYY-MM-DD"
.send_if_error (bool) – Defaults to False. If False, when sending cards to several recipients, if one of the card sends fails, all other card sends will be haulted. If True, only the cards that fail will be haulted, the rest will be scheduled as normal.
- Returns:
AMcards’
response
for sending multiple cards.- Return type:
- Raises:
CardsSendError – When something goes wrong when attempting to send cards.
AuthenticationError – When the client’s
access_token
is invalid.ForbiddenTemplateError – When the client does not own the
template
specified bytemplate_id
.ShippingAddressError – When some items in
shipping_addresses
are missing some required keys.DateFormatError – When one of the dates provided is not in
"YYYY-MM-DD"
format.InsufficientCreditsError – When the client’s user has insufficient credits in their balance.
- template(id: str | int) Template ¶
Fetches client’s AMcards template with a specified id.
- Parameters:
id (str or int) – Unique id for the
template
you are fetching.- Returns:
The client’s
template
with specifiedid
.- Return type:
- Raises:
ForbiddenTemplateError – When the template for the specified
id
either does not exist or is not owned by the client’s user.AuthenticationError – When the client’s
access_token
is invalid.
- templates(limit: int = 25, skip: int = 0) List[Template] ¶
Fetches client’s AMcards templates.
- Parameters:
limit (int) – Defaults to
25
. Max number of templates to be fetched.skip (int) – Defaults to
0
. Number of templates to be skipped.
- Returns:
The client’s
templates
.- Return type:
List[
Template
]- Raises:
AuthenticationError – When the client’s
access_token
is invalid.
- user() User ¶
Fetches client’s AMcards user.
- Returns:
The client’s
user
.- Return type:
- Raises:
AuthenticationError – When the client’s
access_token
is invalid.
amcards.models¶
- class amcards.models.Campaign(id: int, name: str, send_if_duplicate: bool, has_anniversary_drip: bool = False, has_birthday_drip: bool = False)¶
Bases:
object
Represents an AMcards drip campaign.
- property has_anniversary_drip: bool¶
True if one of more drips in this campaign are anniversary drips. False otherwise.
- property has_birthday_drip: bool¶
True if one of more drips in this campaign are birthday drips. False otherwise.
- property id: int¶
Drip campaign’s unique identifier.
- property name: str¶
Drip campaign’s name.
- property send_if_duplicate: bool¶
If True, AMcards will not attempt to detect and prevent duplicates. Otherwise, if this campaign has been previously sent to a contact, further campaign send attempts to the same contact will be prevented.
- class amcards.models.CampaignResponse(mailing_id: int, card_ids: List[int], user_email: str, message: str, shipping_address: dict)¶
Bases:
object
Represents AMcards’ response for sending a single drip campaign.
- property mailing_link: str¶
This is the link to the mailing list inside of AMcards.com.
- property message: str¶
Represents AMcards’ response message for sending a single drip campaign.
- property shipping_address: dict¶
Shipping address for this CampaignResponse.
- property user_email: str¶
Client’s user email.
- class amcards.models.Card(id: int, amount_charged: int, status: CardStatus, initiator: str, send_date: str, date_created: datetime, date_last_modified: datetime, date_fulfilled: datetime, is_international: bool, template_name: str, thumbnail: str, campaign_id: Optional[int], shipping_address: dict, return_address: dict)¶
Bases:
object
Represents an AMcards card.
- property amount_charged: int¶
Total amount charged to client’s user in cents.
- property campaign_id: Optional[int]¶
Unique identifier for drip campaign associated with this card. If this card is not a part of a drip campaign, this value will be
None
.
- property cancel_link: str¶
This is the link to cancel the card inside of AMcards.com.
- property date_created: datetime¶
Date and time card was created.
- property date_fulfilled: Optional[datetime]¶
Date and time card was fulfilled.
None
if not fulfilled yet.
- property date_last_modified: Optional[datetime]¶
Date and time card was last modified.
None
if not modified yet.
- property edit_link: str¶
This is the link to edit the card inside of AMcards.com.
- property id: int¶
Card’s unique identifier.
- property initiator: str¶
Unique identifier of client’s user so if multiple users use a single AMcards.com account, a card can be identified per person.
- property is_international: bool¶
If True, card was shipped international. If False, card was shipped domestic.
- property return_address: dict¶
Return address for the card. In the form:
{ 'first_name': 'Ralph', # OPTIONAL 'last_name': 'Mullins', # OPTIONAL 'address_line_1': '2285 Reppert Road', # OPTIONAL 'city': 'Southfield', # OPTIONAL 'state': 'MI', # OPTIONAL 'postal_code': '48075', # OPTIONAL 'country': 'US', # OPTIONAL }
- property send_date: str¶
The date the card is sent. The format should be:
"YYYY-MM-DD"
.
- property shipping_address: dict¶
Shipping address for the card. In the form:
{ 'first_name': 'Ralph', 'last_name': 'Mullins', 'address_line_1': '2285 Reppert Road', 'city': 'Southfield', 'state': 'MI', 'postal_code': '48075', 'country': 'US', 'organization': 'Google', # OPTIONAL 'third_party_contact_id': 'crmid1453131' # OPTIONAL }
- property status: CardStatus¶
Current status of card.
- property template_name: str¶
Name of template for this card.
- property thumbnail: str¶
Url of thumbnail for this card.
- class amcards.models.CardResponse(card_id: int, total_cost: int, user_email: str, message: str, shipping_address: dict)¶
Bases:
object
Represents AMcards’ response for sending a single card.
- property cancel_link: str¶
This is the link to cancel the card inside of AMcards.com.
- property edit_link: str¶
This is the link to edit the card inside of AMcards.com.
- property message: str¶
AMcards’ response message for sending a single card.
- property shipping_address: dict¶
Shipping address for this CardResponse.
- property total_cost: int¶
Total cost the client’s user was charged in cents.
- property user_email: str¶
Client’s user email.
- class amcards.models.CardStatus(value)¶
Bases:
Enum
Represents the status of an AMcards card.
- DELIVERED = 4¶
- EDITABLE = 0¶
- FLAGGED = 3¶
- IN_THE_MAIL = 2¶
- PRINTED = 6¶
- PROCESSING = 7¶
- READY_FOR_PRINT = 5¶
- REFUNDED = 8¶
- TESTING = 9¶
- VERIFYING_ADDRESS = 1¶
- class amcards.models.CardsResponse(mailing_id: int, user_email: str, message: str, shipping_addresses: List[dict])¶
Bases:
object
Represents AMcards’ response for sending multiple cards.
- property message: str¶
AMcards’ response message for sending multiple cards.
- property shipping_addresses: List[dict]¶
Shipping addresses for this CardsResponse.
- property user_email: str¶
Client’s user email.
- class amcards.models.Contact(id: int, date_created: datetime, date_last_modified: Optional[datetime], date_last_card_send: Optional[datetime], notes: Optional[str], email: Optional[str], first_name: str, last_name: str, address_line_1: str, city: str, state: str, postal_code: str, country: Optional[str], organization: Optional[str], phone: Optional[str], birth_year: Optional[str], birth_month: Optional[str], birth_day: Optional[str], anniversary_year: Optional[str], anniversary_month: Optional[str], anniversary_day: Optional[str])¶
Bases:
object
Represents an AMcards contact.
- property address_line_1: str¶
Contact’s primary address line.
- property anniversary_day: Optional[str]¶
Contact’s anniversary day in the form
"DD"
.None
if contact doesn’t have an anniversary day.
- property anniversary_month: Optional[str]¶
Contact’s anniversary month in the form
"MM"
.None
if contact doesn’t have an anniversary month.
- property anniversary_year: Optional[str]¶
Contact’s anniversary year in the form
"YYYY"
.None
if contact doesn’t have an anniversary year.
- property birth_day: Optional[str]¶
Contact’s birth day in the form
"DD"
.None
if contact doesn’t have a birth day.
- property birth_month: Optional[str]¶
Contact’s birth month in the form
"MM"
.None
if contact doesn’t have a birth month.
- property birth_year: Optional[str]¶
Contact’s birth year in the form
"YYYY"
.None
if contact doesn’t have a birth year.
- property city: str¶
Contact’s city.
- property country: Optional[str]¶
Contact’s country.
None
if contact doesn’t have a country.
- property date_created: datetime¶
Date and time contact was created.
- property date_last_card_send: Optional[datetime]¶
Date and time card was last sent to contact.
None
if card has never been sent to this contact.
- property date_last_modified: Optional[datetime]¶
Date and time contact was last modified.
None
if never modified.
- property email: Optional[str]¶
Contact’s email address.
None
if contact doesn’t have an email address.
- property first_name: str¶
Contact’s first name.
- property id: int¶
Contact’s unique identifier.
- property last_name: str¶
Contact’s last name.
- property notes: Optional[str]¶
Contact’s notes.
None
if contact has no notes.
- property organization: Optional[str]¶
Contact’s organization/company.
None
if contact doesn’t have an organization.
- property phone: Optional[str]¶
Contact’s phone number.
None
if contact doesn’t have a phone number.
- property postal_code: str¶
Contact’s postal code.
- property state: str¶
Contact’s state/province.
- class amcards.models.Gift(name: str, thumbnail: str, base_cost: int, shipping_and_handling_cost: int)¶
Bases:
object
Represents an AMcards gift.
- property base_cost: int¶
Gift’s base cost in cents.
- property name: str¶
Gift’s name.
- property shipping_and_handling_cost: int¶
Gift’s shipping and handling cost in cents.
- property thumbnail: str¶
Gift’s image thumbnail.
- property total_cost: int¶
Gift’s total cost, including
base_cost
+shipping_and_handling_cost
in cents.
- class amcards.models.Mailing(id: int)¶
Bases:
object
Represents an AMcards mailing.
- property id: int¶
Mailing’s unique identifier.
- property mailing_link: str¶
This is the link to the mailing list inside of AMcards.com.
- class amcards.models.MailingStatus(value)¶
Bases:
Enum
Represents the status of an AMcards mailing.
- COMPLETE = 0¶
- PROCESSING = 1¶
- class amcards.models.Template(id: int, name: str, message: str, thumbnail: str, gifts: List[Gift])¶
Bases:
object
Represents an AMcards template.
- property gifts_total: int¶
Sum of gifts’ total costs in cents.
- property id: int¶
Template’s unique identifier.
- property message: str¶
Template’s message on default panel.
- property name: str¶
Template’s name.
- property thumbnail: str¶
Template’s image thumbnail.
- class amcards.models.User(id: int, first_name: str, last_name: str, credits: int, email: str, date_joined: datetime, address_line_1: str, city: str, state: str, postal_code: str, country: str, domestic_postage_cost: int, international_postage_cost: int, domestic_postage_countries: set, greeting_card_cost: int)¶
Bases:
object
Represents an AMcards user.
- property address_line_1: str¶
User’s primary address line (street).
- property city: str¶
User’s state.
- property country: str¶
User’s country.
- property credits: int¶
User’s credit balance in cents.
- property date_joined: datetime¶
Date and time when user created their AMcards account.
- property domestic_postage_cost: int¶
User’s postage cost for sending cards to countries in
domestic_postage_countries
.
- property domestic_postage_countries: set¶
User’s countries that have a
domestic_postage_cost
.
- property email: str¶
User’s email address.
- property first_name: str¶
User’s first name.
- property greeting_card_cost: int¶
User’s base cost of a greeting card excluding postage.
- property id: int¶
User’s unique identifier.
- property international_postage_cost: int¶
User’s postage cost for sending cards to countries not in
domestic_postage_countries
.
- property last_name: str¶
User’s last name.
- property postal_code: str¶
User’s postal code
- property state: str¶
User’s state/province.
amcards.exceptions¶
- exception amcards.exceptions.AMcardsException(*args: object)¶
Bases:
Exception
Base exception for all exceptions raised by AMcards
- exception amcards.exceptions.AuthenticationError(*args: object)¶
Bases:
AMcardsException
Access token provided to client is unauthorized
- exception amcards.exceptions.CampaignSendError(*args: object)¶
Bases:
AMcardsException
Something went wrong when attempting to send a drip campaign
- exception amcards.exceptions.CardSendError(*args: object)¶
Bases:
AMcardsException
Something went wrong when attempting to send a card
- exception amcards.exceptions.CardsSendError(*args: object)¶
Bases:
AMcardsException
Something went wrong when attempting to send cards
- exception amcards.exceptions.DateFormatError(*args: object)¶
Bases:
AMcardsException
,ValueError
Invalid format for date
- exception amcards.exceptions.DuplicateCampaignError(*args: object)¶
Bases:
AMcardsException
Duplicate campaign detected
- exception amcards.exceptions.ForbiddenCampaignError(*args: object)¶
Bases:
ForbiddenResourceError
Campaign is not owned by clients’ user
- exception amcards.exceptions.ForbiddenCardError(*args: object)¶
Bases:
ForbiddenResourceError
Card is not owned by clients’ user
- exception amcards.exceptions.ForbiddenContactError(*args: object)¶
Bases:
ForbiddenResourceError
Contact is not owned by clients’ user
- exception amcards.exceptions.ForbiddenMailingError(*args: object)¶
Bases:
ForbiddenResourceError
Mailing is not owned by clients’ user
- exception amcards.exceptions.ForbiddenResourceError(*args: object)¶
Bases:
AMcardsException
Base exception for when client attempts to access a resource it does not have permission to
- exception amcards.exceptions.ForbiddenTemplateError(*args: object)¶
Bases:
ForbiddenResourceError
Template is not owned by clients’ user
- exception amcards.exceptions.InsufficientCreditsError(*args: object)¶
Bases:
AMcardsException
Clients’ user has insufficient credits
- exception amcards.exceptions.OAuthTokenRefreshError(*args: object)¶
Bases:
AMcardsException
Something went wrong when attempting to refresh AMcards access_token
- exception amcards.exceptions.PhoneFormatError(*args: object)¶
Bases:
AMcardsException
,ValueError
Invalid format for phone number
- exception amcards.exceptions.ShippingAddressError(*args: object)¶
Bases:
AMcardsException
,ValueError
Some shipping address fields are missing or invalid