Transmissions

Use the /transmissions endpoint to send payment information to a recipient securely by email or fax. The transmission includes details for a single-use virtual card, along with optional metadata that is relevant to the payment. For example, you might need to forward booking details to a hotel to fulfill a travel service you provide.

For each transmission, you must specify a template that defines the layout and formatting of the content included. The Marqeta platform provides a basic template (named "default") that displays the virtual card alongside a table of metadata.

  • Fax transmissions include the payment card data and metadata printed on the page.
  • Email transmissions include a secure link to the payment card information and metadata. By default, the link expires 48 hours after creation and can only be accessed three times before becoming non-functional.

Note: If you are interested in using this feature, contact your Marqeta Customer Success representative for more information.

Create and send transmission

Action: POST
Endpoint: /transmissions

A transmission is an email or fax sent to a recipient and includes a single-use virtual payment card with optional message and metadata. The transmission is formatted based on the specified template.

When you create a new transmission, the Marqeta platform automatically sends it to the specified recipient—you do not need to make a separate API call. The Marqeta platform response includes the transmission_outbounds object, which you can use to track the state of each send attempt.

The following image shows a sample fax transmission:

The following image shows a sample email transmission:

Body field details

Name Type Required? Description Allowable Values
token string No The unique identifier of the transmission.

If you do not include a token, the system will generate one automatically. This token is necessary for use in other API calls. This value cannot be updated.
36 char max
transmission_method string Yes The channel by which a transmission is sent. EMAIL | FAX
card_token string Yes The token that identifies the single-use virtual card to include in the transmission. An existing single-use virtual card token.

Submit a GET to /cards/user/{token} to retrieve card tokens for a particular user.
fax_recipient string No The fax number of the intended recipient.

Required if transmission_method is FAX.
Format your fax number as +(country code)(area code)(fax number) with no spaces or hyphens. For example, +1231231234.
email_recipient string No The email address of the intended recipient.

Required if transmission_method is EMAIL.
255 char max
from string No If transmission_method is FAX, the fax number of the transmission sender to be printed on the transmission.

If transmission_method is EMAIL, the email address that populates the 'from' field of the email message. If an email address without a "marqeta.com" domain is provided, the email address that populates the 'reply-to' field of the email message.

Note: If no email address is provided, or if the email address provided does not use the "marqeta.com" domain, the 'from' field of the email message is populated with "no-reply@marqeta.com".
If transmission_method is FAX, format your fax number as +(country code)(area code)(fax number) with no spaces or hyphens. For example, +1231231234.
recipient string Yes A descriptive name of the fax or email recipient. 255 char max
subject string Yes A high-level subject line description of the transmission contents. 255 char max
message string No The message body of the transmission. 1024 char max
logo_location string No The URL of the logo that appears in the fax template or email message. A valid URL for an image no larger than 250 x 250.

Supported image formats include GIF, PNG, and JPG.
metadata object No An object containing custom metadata.
template_token string Yes The token that identifies the template to use with the transmission; the template defines the layout and formatting of the transmission. A template token, or "default".

The metadata object

Name Type Required? Description Allowable Values
custom_name_01
custom_name_02

...

custom_name_20

(255 char max per name)
string No Custom data transmitted with the card data. You can define the names and values of up to 20 fields, for example:

"metadata": {
  "my_name_1": "my_value_1",
  "my_name_2": "my_value_2"
  }
Up to 20 name-value pairs.

255 char max per name; 255 char max per value.

The transmission_outbounds object (response only)

Name Type Description Allowable Values
state string The status of the transmission outbound.
  • QUEUED – The transmission is ready and will be sent soon.
  • SENT – The transmission was sent to the recipient.
  • FAILED – The transmission was not sent; you must resend the transmission.
Note: Submit a GET to /transmissions/{token} to retrieve the transmission record and review its state.
QUEUED | SENT | FAILED
link_expiration_time string The date and time when the link sent in the transmission email expires. yyyy-MM-dd HH:mm:ss

Sample request body

{
"transmission_method": "EMAIL",
"card_token": "e02cf1fa-75a5-48ab",
"email_recipient": "reservations@hotel.com",
"from": "sender@business.com",
"recipient": "John S",
"subject": "Hotel reservation",
"logo_location": "https://assets.marqeta.com/assets/marqeta_mark-64f44306840a5af3aad1aa4b4bd54ddd7e85435e578e4a90b5c16205f45a1e63.png",
"template_token": "zabz8b83-afdb-4afd-ac4e-49bc7cde6ccc",
"metadata": {
"hotel_name": "Hilton",
"total_days": "3"
}
}

Sample response body

{
"token": "4441064f-0f8e-4eed-aad8-d7d756b5ecc7",
"transmission_method": "EMAIL",
"card_token": "e02cf1fa-75a5-48ab",
"email_recipient": "reservations@hotel.com",
"from": "sender@business.com",
"recipient": "John S",
"subject": "Hotel reservation",
"logo_location": "https://assets.marqeta.com/assets/marqeta_mark-64f44306840a5af3aad1aa4b4bd54ddd7e85435e578e4a90b5c16205f45a1e63.png",
"template_token": "zabz8b83-afdb-4afd-ac4e-49bc7cde6ccc",
"metadata": {
"hotel_name": "Hilton",
"total_days": "3"
},
"created_time": "2018-02-05 18:59:57",
"last_modified_time": "2018-02-05 18:59:58",
"transmission_outbounds": [
{
"state": "SENT",
"link_expiration_time": "2018-02-05 19:59:57",
"created_time": "2018-02-05 18:59:57",
"last_modified_time": "2018-02-05 18:59:57"
}
],
"transmission_attempt_count": 1
}


Resend transmission

Action: PUT
Endpoint: /transmissions/{token}/resend

Resend a specific transmission. You can resend transmissions up to three times.

URL path parameters

Name Type Required? Description Allowable Values
token string Yes The identifier of the transmission. An existing transmission token.

Submit a GET to /transmissions to retrieve transmission tokens.

Sample response body

{
"token": "9f2a1457-7471-4efd-a967-bc58194db8a4",
"transmission_method": "EMAIL",
"card_token": "e02cf1fa-75a5-48ab",
"email_recipient": "reservations@hotel.com",
"from": "sender@business.com",
"recipient": "John S",
"subject": "Hotel reservation",
"logo_location": "https://assets.marqeta.com/assets/marqeta_mark-64f44306840a5af3aad1aa4b4bd54ddd7e85435e578e4a90b5c16205f45a1e63.png",
"template_token": "65452623-f049-49ea-8fcc-61ff039f4b50",
"metadata": {
"hotel_name": "Hilton",
"total_days": "3"
},
"created_time": "2018-02-05 19:43:49",
"last_modified_time": "2018-02-05 20:50:45",
"transmission_outbounds": [
{
"state": "SENT",
"link_expiration_time": "2018-02-05 20:43:54",
"created_time": "2018-02-05 19:43:54",
"last_modified_time": "2018-02-05 19:43:54"
},
{
"state": "SENT",
"link_expiration_time": "2018-02-05 21:50:42",
"created_time": "2018-02-05 20:50:42",
"last_modified_time": "2018-02-05 20:50:42"
}
],
"transmission_attempt_count": 2
}


List transmissions

Action: GET
Endpoint: /transmissions

List existing transmissions. This endpoint supports pagination and field filtering.

Query parameters

Name Type Required? Description Allowable Values
transmission_method string No Returns transmissions sent by the specified method. EMAIL | FAX
card_token string No Returns transmissions associated with the specified card. An existing single-use virtual card token.

Submit a GET to /cards/user/{token} to retrieve card tokens for a particular user.
from string No Returns transmissions from the given email address. 255 char max
recipient string No Returns transmissions associated with the specified recipient. 255 char max
template_token string No Returns templates using the specified template token. A template token, or "default".

Sample response body

{
"count": 2,
"start_index": 0,
"end_index": 1,
"is_more": true,
"data": [
{
"token": "40cz0068-6c02-4za9-b4cd-6145cfffa36z",
"transmission_method": "EMAIL",
"card_token": "e02cf1fa-75a5-48ab",
"email_recipient": "reservations@hotel.com",
"from": "sender@business.com",
"recipient": "John S",
"subject": "Your reservation",
"template_token": "6abf8b83-afdb-4afd-ac4e-49bc7cde6ccc",
"metadata": {
"hotel_name": "Hilton",
"total_days": "3"
},
"created_time": "2018-01-25 10:08:04",
"last_modified_time": "2018-01-25 10:08:09",
"transmission_outbounds": [
{
"state": "FAILED",
"link_expiration_time": "2018-01-25 11:08:07",
"created_time": "2018-01-25 10:08:07",
"last_modified_time": "2018-01-25 10:08:07"
}
],
"transmission_attempt_count": 1
},
{
"token": "4825e50c-ec16-420f-a48d-dea80e163c70",
"transmission_method": "EMAIL",
"card_token": "e02cf1fa-75a5-48ab",
"email_recipient": "reservations@hotel.com",
"from": "sender@business.com",
"recipient": "John S",
"subject": "Hotel reservation",
"template_token": "5c66f6ac-5c31-4fa0-b183-13e9097cb4de",
"metadata": {
"hotel_name": "Hilton",
"total_days": "3"
},
"created_time": "2018-02-05 18:59:57",
"last_modified_time": "2018-02-05 18:59:58",
"transmission_outbounds": [
{
"state": "SENT",
"link_expiration_time": "2018-02-05 20:43:54",
"created_time": "2018-02-05 19:43:54",
"last_modified_time": "2018-02-05 19:43:54"
}
],
"transmission_attempt_count": 1
}
]
}


Retrieve transmission

Action: GET
Endpoint: /transmissions/{token}

Retrieve a specific transmission.

URL path parameters

Name Type Required? Description Allowable Values
token string Yes The identifier of the transmission. An existing transmission token.

Sample response body

{
"token": "9f2a1457-7471-4efd-a967-bc58194db8a4",
"transmission_method": "EMAIL",
"card_token": "e02cf1fa-75a5-48ab",
"email_recipient": "reservations@hotel.com",
"from": "sender@business.com",
"recipient": "John S",
"subject": "Hotel reservation",
"template_token": "65452623-f049-49ea-8fcc-61ff039f4b50",
"metadata": {
"hotel_name": "Hilton",
"total_days": "3"
},
"created_time": "2018-02-05 19:43:49",
"last_modified_time": "2018-02-05 20:50:45",
"transmission_outbounds": [
{
"state": "SENT",
"link_expiration_time": "2018-02-05 20:43:54",
"created_time": "2018-02-05 19:43:54",
"last_modified_time": "2018-02-05 19:43:54"
},
{
"state": "SENT",
"link_expiration_time": "2018-02-05 21:50:42",
"created_time": "2018-02-05 20:50:42",
"last_modified_time": "2018-02-05 20:50:42"
}
],
"transmission_attempt_count": 2
}