Mailing endpoints

We provide multiple APIS to perform mailing operations with the WalletApp platform.

Note

Api's that perform bulk operations like the /mails endpoint will behave asynchronously. This means that the response will be a batch id that can be used to check the status of the batch. The webhook call will always be formatted like the following:

Succes webhook

{
    "status": "success",
    "batch_id": "<batch_id>",
    "link": "<link_where_results_can_be_fetched>"
}

Failed webhook

{
    "status": "failed",
    "batch_id": "<batch_id>",
    "error": "<error_message>"
}

The link provided in the webhook will be the correctly formatted link to fetch the results of the batch. This are the same as the status calls for a specific batch type.

GET/templates

Templates

This endpoint will list all email template for a specific organization

Required headers

Name
Authorization
Type
string
Description
The token itself as a bearer token.

Abilities

Name
templates.get
Type
string
Description
The scope required to access this endpoint.

QUERY parameters

Name
brand_id
Type
string|Required
Description
The brand id to get the templates for.

Request

GET

/templates

curl -X GET https://api.walletapp.co/templates
-H "Content-Type: application/json"
-H "Accept: application/json"
-H "Authorization: Bearer <your_token>"
-d '{
    "brand_id": "<brand_id>"
}'

Response

{
    "success": true,
    "data": [
        {
            "identifier": "<identifier>",
            "title": "<title>",
            "subject": "<subject>",
            "sender": "<sender>"
        }
    ]
}

GET/templates/:id

Inspect template

This endpoint will return the template with the given id

Required headers

Name
Authorization
Type
string
Description
The token itself as a bearer token.

Abilities

Name
templates.get
Type
string
Description
The scope required to access this endpoint.

Route parameters

Name
:id
Type
string|Required
Description
The identifier of the template

Request

GET

/templates/:id

curl -X GET https://api.walletapp.co/templates/:id
-H "Content-Type: application/json"
-H "Accept: application/json"
-H "Authorization: Bearer <your_token>"

Response

{
    "success": true,
    "data": {
        "identifier": "<template_id>",
        "title": "<title>",
        "subject": "<subject>",
        "sender": "<sender>",
        "brand_id": "<brand_id>",
        "html": "<html>",
        "reserved_tags": [
            "<tags>",
            ... 
        ],
        "custom_tags": [
            "<tags>",
            ...
        ]
    }
}

POST/mail

Send mail

This endpoint allows you to send a single mail to a member.

Note

Its a good thing to mention that you can provide a user object with customer tags, the user.identifier is always required. When you fetch a mail template using the template/inspect call it will return custom_tags and reserved_tags, both the arrays can be provided as properties of the user object. The custom_tags are the tags that you can use in your template, the reserved_tags are the tags that are reserved for the system, they can be used and will overwrite the system values.

Required headers

Name
Authorization
Type
string
Description
The token itself as a bearer token.

Abilities

Name
templates.store
Type
string
Description
The scope required to access this endpoint.

body parameters

Name
brand_id
Type
string|Required
Description
The brand id to get the members for.
Name
template_id
Type
string|Required
Description
The identifier of the storecard that needs to be used for this request.
Name
user
Type
object|Required
Description
The user you want to send the mail to, consist out of the following properties: [identifier, custom_merge_tags]
Name
coupon_id
Type
string|Optional
Description
You can provide a coupon_id, it will create a pass which will be prefilled in the link_to_pass merge_tag.
Name
storecard_id
Type
string|Optional
Description
You can provide a storecard, it will create a pass which will be prefilled in the link_to_pass merge_tag.
Name
pass_identifier
Type
string|Optional
Description
You can provide a pass_identifier which will be applied as the qr_code for the storecard.

If you provide the coupon_id and the storecard_id than the storecard_id will be used.

Request

POST

/mail

curl -X POST https://api.walletapp.co/mail
-H "Content-Type: application/json"
-H "Accept: application/json"
-H "Authorization: Bearer <your_token>"
-d '{
        "brand_id": "<brand_id>",
        "template_id": "<template_id>",
        "coupon_id": "<coupon_id>",
        "storecard_id": "<storecard_id>",
        "pass_identifier": "<pass_identifier>",
        "user": {
            "identifier": "<member_id>",
            "custom_tag": "<tag>"
        }
    }'

Response

{
    "message": "Request successful",
    "data": {
        "<member_id>": {
            "status": "<mailing_status>",
            "transaction_id": "<transaction_id>"
        }
    }
}

POST/mails

Send mails in bulk

This endpoint allows you to send a mails in bulk, this is an asynchronous API.

Note

Its a good thing to mention that you can provide a users object with customer tags, the user.identifier is always required. When you fetch a mail template using the template/inspect call it will return custom_tags and reserved_tags, both the arrays can be provided as properties of the user object. The custom_tags are the tags that you can use in your template, the reserved_tags are the tags that are reserved for the system, they can be used and will overwrite the system values.

Required headers

Name
Authorization
Type
string
Description
The token itself as a bearer token.

Abilities

Name
templates.store
Type
string
Description
The scope required to access this endpoint.

body parameters

Name
brand_id
Type
string|Required
Description
The brand id to get the members for.
Name
template_id
Type
string|Required
Description
The identifier of the storecard that needs to be used for this request.
Name
users
Type
array|Required
Description
The users you want to send the mail to, consist out of the following properties: [identifier, custom_merge_tags]
Name
coupon_id
Type
string|Optional
Description
You can provide a coupon_id, it will create a pass which will be prefilled in the link_to_pass merge_tag.

Request

POST

/mails

curl -X POST https://api.walletapp.co/mails
-H "Content-Type: application/json"
-H "Accept: application/json"
-H "Authorization: Bearer <your_token>"
-d '{
        "brand_id": "<brand_id>",
        "template_id": "<template_id>",
        "webhook_url": "<url>",
        "coupon_id": "<coupon_id>",
        "users": [ 
            {
                "identifier": "<member_id>",
                "custom_tag": "<tag>"        
            },
            ...
        ]
    }'

Response

{
    "message": "Request successful",
    "data": {
        "webhook_url": "<hook_url>",
        "batch_id": "<uuid>",
        "queued": [
            "<member_id>",
            ...
        ],
        "not_found": [
            "<member_id>",
            ...
        ]
    }
}

GET/webhooks/mails/:batch_id

Bulk mail status

This endpoint returns the status of a current bulk mail request. this link is also returned in the webhook call.

Required headers

Name
Authorization
Type
string
Description
The token itself as a bearer token.

Abilities

Name
templates.get
Type
string
Description
The scope required to access this endpoint.

body parameters

Name
:batch_id
Type
string|Required
Description
The identifier of the batch.

Request

GET

/webhooks/mails/:batch_id

curl -X GET https://api.walletapp.co/webhooks/mails/:batch_id
-H "Content-Type: application/json"
-H "Accept: application/json"
-H "Authorization: Bearer <your_token>"

Response

{
    "message": "Request successful",
    "data": {
        "requested_at": "<timestamp>",
        "started_processing_at": "<timestamp>",
        "finished_processing_at": "<timestamp>",
        "status": "<status>",
        "mails": [
            {
                "uuid": "<uuid>",
                "mailing_error": "<message>",
                "mailing_status": "<status>",
                "provider_id": "<provider_uuid>",
                "created_at": "<timestamp>",
                "updated_at": "<timestamp>"
            }
        ]
    }
}