openapi: 3.0.3 info: title: Lob Sfm_id API version: 1.20.2 description: "Experience direct mail like never before, with unmatched personalization and scalability \x14 all in one intuitive platform." license: name: MIT url: https://mit-license.org/ contact: name: Lob Developer Experience url: https://support.lob.com/ email: lob-openapi@lob.com termsOfService: https://www.lob.com/legal servers: - url: https://api.lob.com/v1 description: production security: - basicAuth: [] tags: - name: Sfm_id paths: /self_mailers/{sfm_id}: parameters: - in: path name: sfm_id description: id of the self_mailer required: true schema: $ref: '#/components/schemas/sfm_id' get: operationId: self_mailer_retrieve summary: Retrieve description: Retrieves the details of an existing self_mailer. You need only supply the unique self_mailer identifier that was returned upon self_mailer creation. tags: - Sfm_id responses: '200': description: Returns a self_mailer object content: application/json: schema: $ref: '#/components/schemas/self_mailer' example: id: sfm_8ffbe811dea49dcf description: April Campaign metadata: {} to: id: adr_bae820679f3f536b description: null name: HARRY ZHANG company: null phone: null email: null address_line1: 210 KING ST STE 6100 address_line2: null address_city: SAN FRANCISCO address_state: CA address_zip: 94107-1741 address_country: UNITED STATES metadata: {} date_created: '2017-09-05T17:47:53.767Z' date_modified: '2017-09-05T17:47:53.767Z' deleted: true object: address from: id: adr_210a8d4b0b76d77b description: null name: LEORE AVIDAR company: null phone: null email: null address_line1: 210 KING ST STE 6100 address_line2: null address_city: SAN FRANCISCO address_state: CA address_zip: 94107-1741 address_country: UNITED STATES metadata: {} date_created: '2017-09-05T17:47:53.767Z' date_modified: '2017-09-05T17:47:53.767Z' deleted: true object: address url: https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf.pdf?version=v1&expires=1618512040&signature=qvyCqXI1ndBvc4AjvG8FlirqLXEcfmYo4sDrRtabaXMOsX88to9G3K49uIk_aqevvZXe8HoRYD_nWydbQHqaCA outside_template_id: tmpl_a3cb937f26d7eec inside_template_id: tmpl_a3cb937f26d7eec inside_template_version_id: vrsn_bfdf70893b00a85 outside_template_version_id: vrsn_bfdf70893b00a85 carrier: USPS tracking_events: [] thumbnails: - small: https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_small_1.png?version=v1&expires=1618512040&signature=-bipeUHP-hAMcCBSrWM0ZH1VwRdSPNVGGZN9hAZKr6Lh4ly6uxvratVd5LXJCK_zOEMYk_mTWASt0ge7OY6SDA medium: https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_medium_1.png?version=v1&expires=1618512040&signature=ryxN7bsXGtw_GRFSP3Cs3A3IYjxZi3cW9BHDCNgMt6p3nobVmsc_iFHt2e-S7ndAXhhN7nP-MQVov3bt3r37BQ large: https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_large_1.png?version=v1&expires=1618512040&signature=kBrm00xkyCkJNJRHxH8HshFaebtOxnzjVWOs1VVmGMuw8H6OBNcMAMxt9s49K0jlpHoh3Nr9uSncEZMQaaNjAg - small: https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_small_2.png?version=v1&expires=1618512040&signature=3gTgU7Fd3KoT_vNlQnTGptRps5ZgnkhSnPrAwk7L98higIzSwfKoLvuu_DIpMM48dHbxckKT9waR8euJ4KSDBQ medium: https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_medium_2.png?version=v1&expires=1618512040&signature=Ue1lw5CMj7KRx6cMQL8xPeazaHCdJzWcACd1w3acuYPnWkVIpSt62OIO7hAtpAQK9xm1dhhlFj0rqRZMdRMMBA large: https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_large_2.png?version=v1&expires=1618512040&signature=cICc7HEm1xG_eyM4a_wtvPk2FqoLRmtgGa29kJisWnMIYBL0OkyzG4ZCYGMhp-5cZpJlSpXfTgGKh_Qmeo1TDw merge_variables: name: null size: 6x18_bifold mail_type: usps_first_class expected_delivery_date: '2021-03-24' date_created: '2021-03-16T18:40:40.504Z' date_modified: '2021-03-16T18:40:40.504Z' send_date: '2021-03-16T18:45:40.493Z' use_type: marketing fsc: false object: self_mailer default: $ref: '#/components/responses/mailpiece_error' x-codeSamples: - lang: Shell source: "curl -X GET \"https://api.lob.com/v1/self_mailers/sfm_8ffbe811dea49dcf\" \\\n -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:\n" label: CURL - lang: typescript source: "try {\n const selfMailer = await new SelfMailersApi(config).get('sfm_xxxx');\n} catch (err: any) {\n console.error(err);\n}\n" label: TYPESCRIPT - lang: Javascript source: "Lob.selfMailers.retrieve('sfm_8ffbe811dea49dcf', function (err, res) {\n console.log(err, res);\n});\n" label: NODE - lang: Ruby source: "selfMailerApi = SelfMailersApi.new(config)\n\nbegin\n retrievedSelfMailer = selfMailerApi.get(\"sfm_8ffbe811dea49dcf\")\nrescue => err\n p err.message\nend\n" label: RUBY - lang: Python source: "with ApiClient(configuration) as api_client:\n api = SelfMailersApi(api_client)\n\ntry:\n self_mailer = api.get(\"sfm_8ffbe811dea49dcf\")\nexcept ApiException as e:\n print(e)\n" label: PYTHON - lang: PHP source: "$apiInstance = new OpenAPI\\Client\\Api\\SelfMailersApi($config, new GuzzleHttp\\Client());\n\ntry {\n $result = $apiInstance->get(\"sfm_8ffbe811dea49dcf\");\n} catch (Exception $e) {\n echo $e->getMessage(), PHP_EOL;\n}\n" - lang: Java source: "SelfMailersApi apiInstance = new SelfMailersApi(config);\n\ntry {\n SelfMailer response = apiInstance.get(\"sfm_8ffbe811dea49dcf\");\n} catch (ApiException e) {\n e.printStackTrace();\n}\n" label: JAVA - lang: Elixir source: 'Lob.SelfMailer.find("sfm_8ffbe811dea49dcf") ' label: ELIXIR - lang: CSharp source: "SelfMailersApi api = new SelfMailersApi(config);\n\ntry {\n SelfMailer response = api.get(\"sfm_8ffbe811dea49dcf\");\n} catch (ApiException e) {\n Console.WriteLine(e.ToString());\n}\n" label: CSHARP - lang: Go source: "var context = context.Background()\ncontext = context.WithValue(suite.ctx, lob.ContextBasicAuth, lob.BasicAuth{UserName: os.Getenv(\"\")})\n\nvar apiClient = *lob.NewAPIClient(configuration)\n\nfetchedSelfMailer, _, err := apiClient.SelfMailersApi.Get(context,\"sfm_8ffbe811dea49dcf\").Execute()\n\nif err != nil {\n return err\n}\n" label: GO delete: operationId: self_mailer_delete summary: Delete description: Completely removes a self mailer from production. This can only be done if the self mailer's `send_date` has not yet passed. If the self mailer is successfully canceled, you will not be charged for it. This feature is exclusive to certain customers. Upgrade to the appropriate Print & Mail Edition to gain access. tags: - Sfm_id responses: '200': $ref: '#/components/responses/self_mailer_deleted' default: $ref: '#/components/responses/mailpiece_error' x-codeSamples: - lang: Shell source: "curl -X DELETE https://api.lob.com/v1/self_mailers/sfm_8ffbe811dea49dcf \\\n -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:\n" label: CURL - lang: typescript source: "try {\n const deleteSelfMailer = await new SelfMailersApi(config).cancel('sfm_xxxx');\n} catch (err: any) {\n console.error(err);\n}\n" label: TYPESCRIPT - lang: Javascript source: "Lob.selfMailers.cancel('sfm_8ffbe811dea49dcf', function (err, res) {\n console.log(err, res);\n});\n" label: NODE - lang: Ruby source: "selfMailerApi = SelfMailersApi.new(config)\n\nbegin\n deletedSelfMailer = selfMailerApi.cancel(\"sfm_8ffbe811dea49dcf\")\nrescue => err\n p err.message\nend\n" label: RUBY - lang: Python source: "with ApiClient(configuration) as api_client:\n api = SelfMailersApi(api_client)\n\ntry:\n deleted_resource = api.cancel(\"sfm_8ffbe811dea49dcf\")\nexcept ApiException as e:\n print(e)\n" label: PYTHON - lang: PHP source: "$apiInstance = new OpenAPI\\Client\\Api\\SelfMailersApi($config, new GuzzleHttp\\Client());\n\ntry {\n $result = $apiInstance->cancel(\"sfm_8ffbe811dea49dcf\");\n} catch (Exception $e) {\n echo $e->getMessage(), PHP_EOL;\n}\n" - lang: Java source: "SelfMailersApi apiInstance = new SelfMailersApi(config);\n\ntry {\n SelfMailerDeletion response = apiInstance.cancel(\"sfm_8ffbe811dea49dcf\");\n} catch (ApiException e) {\n e.printStackTrace();\n}\n" label: JAVA - lang: Elixir source: 'Lob.SelfMailer.destroy("sfm_8ffbe811dea49dcf") ' label: ELIXIR - lang: CSharp source: "SelfMailersApi api = new SelfMailersApi(config);\n\ntry {\n SelfMailerDeletion response = api.cancel(\"sfm_8ffbe811dea49dcf\");\n} catch (ApiException e) {\n Console.WriteLine(e.ToString());\n}\n" label: CSHARP - lang: Go source: "var context = context.Background()\ncontext = context.WithValue(suite.ctx, lob.ContextBasicAuth, lob.BasicAuth{UserName: os.Getenv(\"\")})\n\nvar apiClient = *lob.NewAPIClient(configuration)\n\ndeletedSelfMailer, _, err := apiClient.SelfMailersApi.Cancel(context, \"sfm_8ffbe811dea49dcf\").Execute()\n\nif err != nil {\n return err\n}\n" label: GO components: schemas: date_created: type: string format: date-time description: A timestamp in ISO 8601 format of the date the resource was created. tracking_event_details: type: object required: - event - description - action_required properties: event: type: string enum: - package_accepted - package_arrived - package_departed - package_processing - package_processed - package_in_local_area - delivery_scheduled - out_for_delivery - pickup_available - delivered - package_forwarded - returned_to_sender - address_issue - contact_carrier - delayed - delivery_attempted - delivery_rescheduled - location_inaccessible - notice_left - package_damaged - package_disposed - package_held - package_lost - package_unclaimed - package_undeliverable - reschedule_delivery - other description: 'Find the full table [here](#tag/Tracking-Events). A detailed substatus about the event: * `package_accepted` - Package has been accepted into the carrier network for delivery. * `package_arrived` - Package has arrived at an intermediate location in the carrier network. * `package_departed` - Package has departed from an intermediate location in the carrier network. * `package_processing` - Package is processing at an intermediate location in the carrier network. * `package_processed` - Package has been processed at an intermediate location. * `package_in_local_area` - Package is at a location near the end destination. * `delivery_scheduled` - Package is scheduled for delivery. * `out_for_delivery` - Package is out for delivery. * `pickup_available` - Package is available for pickup at carrier location. * `delivered` - Package has been delivered. * `package_forwarded` - Package has been forwarded. * `returned_to_sender` - Package is to be returned to sender. * `address_issue` - Address information is incorrect. Contact carrier to ensure delivery. * `contact_carrier` - Contact the carrier for more information. * `delayed` - Delivery of package is delayed. * `delivery_attempted` - Delivery of package has been attempted. Contact carrier to ensure delivery. * `delivery_rescheduled` - Delivery of package has been rescheduled. * `location_inaccessible` - Delivery location inaccessible to carrier. Contact carrier to ensure delivery. * `notice_left` - Carrier left notice during attempted delivery. Follow carrier instructions on notice. * `package_damaged` - Package has been damaged. Contact carrier for more details. * `package_disposed` - Package has been disposed. * `package_held` - Package held at carrier location. Contact carrier for more details. * `package_lost` - Package has been lost. Contact carrier for more details. * `package_unclaimed` - Package is unclaimed. * `package_undeliverable` - Package is not able to be delivered. * `reschedule_delivery` - Contact carrier to reschedule delivery. * `other` - Unrecognized carrier status. ' description: type: string description: The description as listed in the description for event. notes: type: string description: Event-specific notes from USPS about the tracking event. action_required: type: boolean description: '`true` if action is required by the end recipient, `false` otherwise. ' adr_id: type: string description: Unique identifier prefixed with `adr_`. pattern: ^adr_[a-zA-Z0-9]+$ error: type: object description: Lob uses RESTful HTTP response codes to indicate success or failure of an API request. In general, 2xx indicates success, 4xx indicate an input error, and 5xx indicates an error on Lob's end. required: - error properties: error: type: object required: - message - status_code - code properties: message: type: string description: A human-readable message with more details about the error example: Rate limit exceeded. Please wait 5 seconds and try your request again. status_code: $ref: '#/components/schemas/failure_status_code' code: type: string enum: - bad_request - conflict - feature_limit_reached - internal_server_error - invalid - not_deletable - not_found - request_timeout - service_unavailable - unrecognized_endpoint - unsupported_lob_version - address_length_exceeds_limit - bank_account_already_verified - bank_error - billing_address_required - custom_envelope_inventory_depleted - deleted_bank_account - failed_deliverability_strictness - file_pages_below_min - file_pages_exceed_max - file_size_exceeds_limit - foreign_return_address - inconsistent_page_dimensions - invalid_bank_account - invalid_bank_account_verification - invalid_check_international - invalid_country_covid - invalid_file - invalid_file_dimensions - invalid_file_download_time - invalid_file_url - invalid_image_dpi - invalid_international_feature - invalid_perforation_return_envelope - invalid_template_html - mail_use_type_can_not_be_null - merge_variable_required - merge_variable_whitespace - payment_method_unverified - pdf_encrypted - special_characters_restricted - unembedded_fonts - email_required - invalid_api_key - publishable_key_not_allowed - rate_limit_exceeded - unauthorized - unauthorized_token description: 'A pre-defined string identifying an error. Error codes fall into three categories: **GENERIC** * `bad_request` - 422: an invalid request was made. See error message for details. * `conflict` - 409/422: this operation would leave data in a conflicted state. * `feature_limit_reached` - 403: the account has reached its resource limit and requires upgrading to add more. * `internal_server_error` - 500: an error has occured on Lob''s servers. Please try request again. * `invalid` - 422: an invalid request was made. See error message for details. * `not_deletable` - 422: an attempt was made to delete a resource, but the resource cannot be deleted. * `not_found` - 404: the requested resource was not found. * `request_timeout` - 408: the request took too long. Please try again. * `service_unavailable` - 503: the Lob servers are temporarily unavailable. Please try agian. * `unrecognized_endpoint` - 404: the requested endpoint doesn''t exist. * `unsupported_lob_version` - 422: an unsupported Lob API version was requested. **ADVANCED** * `address_length_exceeds_limit` - 422: the sum of to.address_line1 and to.address_line2 cannot surpass 50 characters. * `bank_account_already_verified` - 422: the bank account has already been verified. * `bank_error` - 422: there''s an issue with the bank account. * `billing_address_required` - 403: in order to create a live mail piece, your account needs to set up a billing address. * `custom_envelope_inventory_depleted` - 422: custom envelope inventory is depleted, and more will need to be ordered. * `deleted_bank_account` - 404: checks cannot be created with a deleted bank account. * `failed_deliverability_strictness` - 422: the `to` address doesn''t meet strictness requirements. See Account Settings to configure strictness. * `file_pages_below_min` - 422: not enough pages. * `file_pages_exceed_max` - 422: too many pages. * `file_size_exceeds_limit` - 422: the file size is too large. See description for details. * `foreign_return_address` - 422: the `from` address must be a US address. * `inconsistent_page_dimensions` - 422: all pages of the input file must have the same dimensions. * `invalid_bank_account` - 422: the provided bank routing number is invalid. * `invalid_bank_account_verification` - 422: verification amounts do not match. * `invalid_check_international` - 422: checks cannot be sent internationally. * `invalid_country_covid` - 422: the postal service in the specified country is currently unable to process the request due to COVID-19 restrictions. * `invalid_file` - 422: the file is invalid. * `invalid_file_dimensions` - 422: file dimensions are incorrect for the selected mail type. * `invalid_file_download_time` - 422: file download from remote server took too long. * `invalid_file_url` - 422: the file URL when creating a resource is invalid. * `invalid_image_dpi` - 422: DPI must be at least 300. * `invalid_international_feature` - 422: the specified product cannot be sent to the destination. * `invalid_perforation_return_envelope` - 422: both `return_envelope` and `perforation` must be used together. * `invalid_template_html` - 422: the provided HTML is invalid. * `mail_use_type_can_not_be_null` - 422: use_type must be one of "marketing" or "operational". Alternatively, an admin can set the account default use type in Account Settings. * `merge_variable_required` - 422: a required merge variable is missing. * `merge_variable_whitespace` - 422: merge variable names cannot contain whitespace. * `payment_method_unverified` - 401: you must have a verified bank account or credit card to submit live requests. * `pdf_encrypted` - 422: an encrypted PDF was provided. * `special_characters_restricted` - 422: cannot use special characters for merge variable names. * `unembedded_fonts` - 422: the provided PDF contains non-standard unembedded fonts. See description for details. **AUTHENTICATION** * `email_required` - 401: account must have a verified email address before creating live resources. * `invalid_api_key` - 401/403: the API key is invalid. * `publishable_key_not_allowed` - 403: the requested operation needs a secret key, not a publishable key. See [API Keys](#section/API-Keys) for more information. * `rate_limit_exceeded` - 429: requests were sent too quickly and must be slowed down. * `unauthorized` - 401: the request isn''t authorized. * `unauthorized_token` - 401: token isn''t authorized. ' signed_link: type: string description: A [signed link](#section/Asset-URLs) served over HTTPS. The link returned will expire in 30 days to prevent mis-sharing. Each time a GET request is initiated, a new signed URL will be generated. pattern: ^https://lob-assets.com/(letters|postcards|bank-accounts|checks|self-mailers|cards|order-creatives)/([a-z]{3,4}_[a-z0-9]{15,16}|[a-z]{3}_[a-z0-9]{26}_[a-z]{4}_[a-z0-9]{26})('|_signature)(.pdf|_thumb_[a-z]+_[0-9]+.png|.png)?(version=[a-z0-9]*&)expires=[0-9]{10}&signature=[a-zA-Z0-9-_]+ tmpl_id: type: string description: Unique identifier prefixed with `tmpl_`. ID of a saved [HTML template](#section/HTML-Templates). pattern: ^tmpl_[a-zA-Z0-9]+$ send_date: type: string description: A timestamp in ISO 8601 format which specifies a date after the current time and up to 180 days in the future to send the letter off for production. Setting a send date overrides the default [cancellation window](#section/Cancellation-Windows) applied to the mailpiece. Until the `send_date` has passed, the mailpiece can be canceled. If a date in the format `2017-11-01` is passed, it will evaluate to midnight UTC of that date (`2017-11-01T00:00:00.000Z`). If a datetime is passed, that exact time will be used. A `send_date` passed with no time zone will default to UTC, while a `send_date` passed with a time zone will be converted to UTC. anyOf: - format: date-time - format: date self_mailer_deletion: description: Lob uses RESTful HTTP response codes to indicate success or failure of an API request. In general, 2xx indicates success, 4xx indicate an input error, and 5xx indicates an error on Lob's end. properties: id: $ref: '#/components/schemas/sfm_id' deleted: $ref: '#/components/schemas/deleted' campaign_id: title: campaign_id description: Denotes resources created by the provided campaign id, prefixed with `cmp_`. In the case of snap packs, booklets, and letters with size `us_legal`, however, the campaign id is prefixed with `camp_` instead of `cmp_`. type: string pattern: ^(cmp|camp)_[a-zA-Z0-9]+$ nullable: true failure_reason: type: object description: An object describing the reason for failure if the resource failed to render. properties: remediation: type: string description: Instructions on how to resolve the error failure_reason: type: string description: Reason failure occurred errors: type: array nullable: true items: $ref: '#/components/schemas/failure_reason_error' company: type: string description: 'Either `name` or `company` is required, you may also add both. Must be no longer than 40 characters. If both `name` and `company` are provided, they will be printed on two separate lines above the rest of the address. This field can be used for any secondary recipient information which is not part of the actual mailing address (Company Name, Department, Attention Line, etc). ' maxLength: 40 nullable: true address_us: allOf: - $ref: '#/components/schemas/lob_base' - type: object required: - id - address_line1 - address_city - address_state - address_zip anyOf: - title: address obj with `name` defined required: - name - title: address obj with `company` defined required: - company properties: id: $ref: '#/components/schemas/adr_id' object: type: string description: Value is resource type. enum: - address default: address description: $ref: '#/components/schemas/resource_description' name: type: string description: 'Either `name` or `company` is required, you may also add both. Must be no longer than 40 characters. If both `name` and `company` are provided, they will be printed on two separate lines above the rest of the address. ' maxLength: 40 nullable: true company: type: string description: 'Either `name` or `company` is required, you may also add both. Must be no longer than 40 characters. If both `name` and `company` are provided, they will be printed on two separate lines above the rest of the address. This field can be used for any secondary recipient information which is not part of the actual mailing address (Company Name, Department, Attention Line, etc). ' maxLength: 40 nullable: true phone: type: string description: Must be no longer than 40 characters. maxLength: 40 nullable: true email: type: string description: Must be no longer than 100 characters. maxLength: 100 nullable: true address_line1: type: string description: The primary number, street name, and directional information. maxLength: 64 address_line2: type: string description: An optional field containing any information which can't fit into line 1. maxLength: 64 nullable: true address_city: type: string maxLength: 200 address_state: type: string description: 2 letter state short-name code pattern: ^[a-zA-Z]{2}$ address_zip: type: string description: 'Must follow the ZIP format of `12345` or ZIP+4 format of `12345-1234`. ' pattern: ^\d{5}(-\d{4})?$ address_country: type: string enum: - UNITED STATES description: Full name of country minLength: 13 maxLength: 13 metadata: $ref: '#/components/schemas/metadata' recipient_moved: type: boolean description: 'Only returned for accounts on certain Print & Mail Editions. Value is `true` if the address was altered because the recipient filed for a National Change of Address Linkage (NCOALink), `false` if the NCOALink check was run but no altered address was found, and `null` if the NCOALink check was not run. The NCOALink check does not happen for non-US addresses, for non-deliverable US addresses, or for addresses created before the NCOALink feature was added to your account. ' nullable: true example: id: adr_e68217bd744d65c8 description: Harry - Office name: HARRY ZHANG company: LOB phone: '5555555555' email: harry@lob.com address_line1: 210 KING ST STE 6100 address_line2: null address_city: SAN FRANCISCO address_state: CA address_zip: 94107-1741 address_country: UNITED STATES metadata: {} recipient_moved: false date_created: '2019-08-12T00:16:00.361Z' date_modified: '2019-08-12T00:16:00.361Z' object: address sfm_use_type: description: The use type for each mailpiece. Can be one of marketing, operational, or null. Null use_type is only allowed if an account default use_type is selected in Account Settings. For more information on use_type, see our [Help Center article](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings/declaring-mail-use-type). type: string enum: - marketing - operational - null nullable: true vrsn_id: type: string description: Unique identifier prefixed with `vrsn_`. pattern: ^vrsn_[a-zA-Z0-9]+$ resource_description: type: string description: 'An internal description that identifies this resource. Must be no longer than 255 characters. ' maxLength: 255 nullable: true thumbnail: type: object properties: small: $ref: '#/components/schemas/signed_link' medium: $ref: '#/components/schemas/signed_link' large: $ref: '#/components/schemas/signed_link' sfm_id: type: string description: Unique identifier prefixed with `sfm_`. pattern: ^sfm_[a-zA-Z0-9]+$ address_intl: allOf: - $ref: '#/components/schemas/lob_base' - type: object required: - id - address_line1 - address_country anyOf: - title: address obj with `name` defined required: - name - title: address obj with `company` defined required: - company properties: id: $ref: '#/components/schemas/adr_id' description: $ref: '#/components/schemas/resource_description' name: type: string description: 'Either `name` or `company` is required, you may also add both. Must be no longer than 40 characters. If both `name` and `company` are provided, they will be printed on two separate lines above the rest of the address. ' maxLength: 40 nullable: true company: $ref: '#/components/schemas/company' phone: type: string description: Must be no longer than 40 characters. maxLength: 40 nullable: true email: type: string description: Must be no longer than 100 characters. maxLength: 100 nullable: true metadata: $ref: '#/components/schemas/metadata' address_line1: type: string maxLength: 200 address_line2: type: string maxLength: 200 nullable: true address_city: type: string maxLength: 200 nullable: true address_state: description: Will be returned as a full string type: string maxLength: 200 nullable: true address_zip: type: string description: Optional postal code. maxLength: 40 nullable: true address_country: description: Full name of country type: string maxLength: 200 enum: - AFGHANISTAN - ALBANIA - ALGERIA - AMERICAN SAMOA - ANDORRA - ANGOLA - ANGUILLA - ANTARCTICA - ANTIGUA AND BARBUDA - ARGENTINA - ARUBA - AUSTRALIA - AUSTRIA - AZERBAIJAN - BAHRAIN - BANGLADESH - BARBADOS - BELARUS - BELGIUM - BELIZE - BENIN - BERMUDA - BHUTAN - BOLIVIA (PLURINATIONAL STATE OF) - BONAIRE, SAINT EUSTATIUS AND SABA - BOSNIA AND HERZEGOVINA - BOTSWANA - BRAZIL - BRITISH INDIAN OCEAN TERRITORY - BRITISH VIRGIN ISLANDS - BRUNEI DARUSSALAM - BULGARIA - BURKINA FASO - BURUNDI - CABO VERDE - CAMBODIA - CAMEROON - CANADA - CAYMAN ISLANDS - CENTRAL AFRICAN REPUBLIC - CHAD - CHILE - CHINA - COLOMBIA - COMOROS - CONGO - CONGO, DEMOCRATIC REPUBLIC OF THE - COOK ISLANDS - COSTA RICA - C�TE D'IVOIRE - CROATIA - CUBA - CURA�AO - CYPRUS - CZECH REPUBLIC - DENMARK - DJIBOUTI - DOMINICA - DOMINICAN REPUBLIC - ECUADOR - EGYPT - EL SALVADOR - EQUATORIAL GUINEA - ERITREA - ESTONIA - ESWATINI - ETHIOPIA - FALKLAND ISLANDS (MALVINAS) - FAROE ISLANDS - FIJI - FINLAND - FRANCE - GABON - GAMBIA - GEORGIA - GERMANY - GHANA - GIBRALTAR - GREECE - GREENLAND - GRENADA - GUATEMALA - GUINEA - GUINEA-BISSAU - GUYANA - HAITI - HOLY SEE - HONDURAS - HONG KONG - HUNGARY - ICELAND - INDIA - INDONESIA - IRAN (ISLAMIC REPUBLIC OF) - IRAQ - IRELAND - ISRAEL - ITALY - JAMAICA - JAPAN - JORDAN - KAZAKHSTAN - KENYA - KIRIBATI - KOREA (DEMOCRATIC PEOPLES REPUBLIC OF) - KOREA, REPUBLIC OF - KUWAIT - KYRGYZSTAN - LAO PEOPLES DEMOCRATIC REPUBLIC - LATVIA - LEBANON - LESOTHO - LIBERIA - LIBYA - LIECHTENSTEIN - LITHUANIA - LUXEMBOURG - MACAO - MACEDONIA - MADAGASCAR - MALAWI - MALAYSIA - MALDIVES - MALI - MALTA - MAURITANIA - MAURITIUS - MEXICO - MOLDOVA, REPUBLIC OF - MONACO - MONGOLIA - MONTENEGRO - MONTSERRAT - MOROCCO - MOZAMBIQUE - MYANMAR - NAMIBIA - NAURU - NEPAL - NETHERLAND ANTILLES - NETHERLANDS - NEW ZEALAND - NICARAGUA - NIGER - NIGERIA - NIUE - NORFOLK ISLAND - NORWAY - OMAN - PAKISTAN - PANAMA - PAPUA NEW GUINEA - PARAGUAY - PERU - PHILIPPINES - PITCAIRN - POLAND - PORTUGAL - QATAR - ROMANIA - RUSSIAN FEDERATION - RWANDA - SAINT HELENA - SAINT KITTS AND NEVIS - SAINT LUCIA - SAINT VINCENT AND THE GRENADINES - SAMOA - SAN MARINO - SAO TOME AND PRINCIPE - SAUDI ARABIA - SENEGAL - SERBIA - SEYCHELLES - SIERRA LEONE - SINGAPORE - SINT MAARTEN - SLOVAKIA - SLOVENIA - SOLOMON ISLANDS - SOMALIA - SOUTH AFRICA - SOUTH GEORGIA AND THE SOUTH SANDWICH ISLANDS - SOUTH SUDAN - SPAIN - SRI LANKA - SUDAN - SURINAME - SWEDEN - SWITZERLAND - SYRIAN ARAB REPUBLIC - TAIWAN - TAJIKISTAN - TANZANIA - THAILAND - THE BAHAMAS - TIMOR-LESTE - TOGO - TOKELAU - TONGA - TRINIDAD AND TOBAGO - TUNISIA - TURKEY - TURKMENISTAN - TURKS AND CAICOS ISLANDS - TUVALU - UGANDA - UKRAINE - UNITED ARAB EMIRATES - UNITED KINGDOM - URUGUAY - UZBEKISTAN - VANUATU - VENEZUELA - VIET NAM - WESTERN SAHARA - YEMEN - ZAMBIA - ZIMBABWE object: type: string description: Value is resource type. enum: - address default: address example: id: adr_e68217bd744d65c8 description: Harry - Office name: Harry Zhang company: Lob phone: '5555555555' email: harry@lob.com metadata: {} address_line1: 370 WATER ST address_line2: '' address_city: SUMMERSIDE address_state: PRINCE EDWARD ISLAND address_zip: C1N 1C4 address_country: CANADA self_mailer_size: type: string enum: - 6x18_bifold - 11x9_bifold - 12x9_bifold - 17.75x9_trifold description: Specifies the size of the self mailer. The `17.75x9_trifold` size is in beta. Contact support@lob.com or your account contact to learn more. default: 6x18_bifold tracking_event_base: type: object description: As mail pieces travel through the mail stream, USPS scans their unique barcodes, and Lob processes these mail scans to generate tracking events. required: - id - date_created - date_modified - object properties: id: $ref: '#/components/schemas/evnt_id' time: type: string format: date-time description: A timestamp in ISO 8601 format of the date USPS registered the event. date_created: $ref: '#/components/schemas/date_created' date_modified: $ref: '#/components/schemas/date_modified' object: allOf: - $ref: '#/components/schemas/object' - type: string enum: - tracking_event default: tracking_event editable: type: object properties: description: $ref: '#/components/schemas/resource_description' metadata: $ref: '#/components/schemas/metadata' mail_type: $ref: '#/components/schemas/mail_type' merge_variables: $ref: '#/components/schemas/merge_variables' send_date: $ref: '#/components/schemas/send_date' evnt_id: type: string description: Unique identifier prefixed with `evnt_`. pattern: ^evnt_[a-zA-Z0-9]+$ mail_type: type: string enum: - usps_first_class - usps_standard description: 'A string designating the mail postage type: * `usps_first_class` - (default) * `usps_standard` - a cheaper option which is less predictable and takes longer to deliver. `usps_standard` cannot be used with `4x6` postcards or for any postcards sent outside of the United States. ' default: usps_first_class deleted: type: boolean description: Only returned if the resource has been successfully deleted. self_mailer_base: allOf: - $ref: '#/components/schemas/editable' - type: object properties: size: $ref: '#/components/schemas/self_mailer_size' generated: type: object required: - to - carrier properties: to: $ref: '#/components/schemas/address' carrier: type: string enum: - USPS default: USPS thumbnails: type: array items: $ref: '#/components/schemas/thumbnail' expected_delivery_date: $ref: '#/components/schemas/expected_delivery_date' date_created: $ref: '#/components/schemas/date_created' date_modified: $ref: '#/components/schemas/date_modified' deleted: $ref: '#/components/schemas/deleted' from_us: type: object properties: from: $ref: '#/components/schemas/address_us' lob_base: type: object required: - date_created - date_modified - object properties: date_created: $ref: '#/components/schemas/date_created' date_modified: $ref: '#/components/schemas/date_modified' deleted: $ref: '#/components/schemas/deleted' object: $ref: '#/components/schemas/object' merge_variables: type: object description: 'You can input a merge variable payload object to your template or QR code redirect URLs to render dynamic content. For example, if you have a template like: `{{variable_name}}`, pass in `{"variable_name": "Harry"}` to render `Harry`. `merge_variables` must be an object. Any type of value is accepted as long as the object is valid JSON; you can use `strings`, `numbers`, `booleans`, `arrays`, `objects`, or `null`. The max length of the object is 25,000 characters. If you call `JSON.stringify` on your object, it can be no longer than 25,000 characters. Your variable names cannot contain any whitespace or any of the following special characters: `!`, `"`, `#`, `%`, `&`, `''`, `(`, `)`, `*`, `+`, `,`, `/`, `;`, `<`, `=`, `>`, `@`, `[`, `\`, `]`, `^`, `` ` ``, `{`, `|`, `}`, `~`. More instructions can be found in our guide to using html and merge variables. Depending on your Merge Variable strictness setting, if you define variables in your HTML but do not pass them here, you will either receive an error or the variable will render as an empty string. These settings only apply on HTML templates and not on QR code redirect URLs.' maxLength: 25000 nullable: true metadata: type: object additionalProperties: type: string description: 'Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. ''{"customer_id" : "NEWYORK2015"}'' Nested objects are not supported. See [Metadata](#section/Metadata) for more information.' maxLength: 500 pattern: '[^"\\]{0,500}' address: oneOf: - $ref: '#/components/schemas/address_us' - $ref: '#/components/schemas/address_intl' self_mailer: allOf: - $ref: '#/components/schemas/self_mailer_base' - $ref: '#/components/schemas/generated' - $ref: '#/components/schemas/from_us' - type: object required: - id - url - use_type properties: id: $ref: '#/components/schemas/sfm_id' outside_template_id: description: The unique ID of the HTML template used for the outside of the self mailer. allOf: - $ref: '#/components/schemas/tmpl_id' - type: string nullable: true inside_template_id: description: The unique ID of the HTML template used for the inside of the self mailer. allOf: - $ref: '#/components/schemas/tmpl_id' - type: string nullable: true outside_template_version_id: description: The unique ID of the specific version of the HTML template used for the outside of the self mailer. allOf: - $ref: '#/components/schemas/vrsn_id' - type: string nullable: true inside_template_version_id: description: The unique ID of the specific version of the HTML template used for the inside of the self mailer. allOf: - $ref: '#/components/schemas/vrsn_id' - type: string nullable: true object: type: string description: Value is resource type. enum: - self_mailer default: self_mailer tracking_events: description: An array of certified tracking events ordered by ascending `time`. Not populated in test mode. type: array items: $ref: '#/components/schemas/tracking_event_certified' use_type: $ref: '#/components/schemas/sfm_use_type' url: $ref: '#/components/schemas/signed_link' fsc: type: boolean description: This is in beta. Contact support@lob.com or your account contact to learn more. Not available for `11x9_bifold` self-mailer size. default: false status: $ref: '#/components/schemas/status' campaign_id: $ref: '#/components/schemas/campaign_id' failure_reason: allOf: - $ref: '#/components/schemas/failure_reason' - nullable: true tracking_event_certified: allOf: - $ref: '#/components/schemas/tracking_event_base' - type: object required: - type - name properties: type: description: a Certified letter tracking event type: string enum: - certified name: type: string enum: - Mailed - In Transit - In Local Area - Processed for Delivery - Pickup Available - Delivered - Re-Routed - Returned to Sender - Issue description: "Name of tracking event for Certified letters. Letters sent with USPS Certified Mail are fully tracked by USPS, therefore their tracking events have an additional details object with more detailed information about the tracking event. Some certified tracking event names have multiple meanings, noted in the list here. See the description of the details object for the full set of combined certified tracking event name meanings.\n\n * `Mailed` - Package has been accepted into the carrier network for delivery.\n\n * `In Transit` - Maps to four distinct stages of transit.\n\n * `In Local Area` - Package is at a location near the end destination.\n\n * `Processed for Delivery` - Maps to two distinct stages of delivery.\n\n * `Pickup Available` - Package is available for pickup at carrier location.\n\n * `Delivered` - Package has been delivered.\n\n * `Re-Routed` - Package has been forwarded.\n\n * `Returned to Sender` - Package is to be returned to sender.\n\n * `Issue` - Maps to (at least) 15 possible issues, some of which are actionable.\n" details: $ref: '#/components/schemas/tracking_event_details' location: type: string description: 'The zip code in which the event occurred if it exists, otherwise will be the name of a Regional Distribution Center if it exists, otherwise will be null. ' nullable: true failure_status_code: type: integer enum: - 401 - 403 - 404 - 413 - 422 - 429 - 500 description: "A conventional HTTP status code:\n * `401` - Authorization error with your API key or account\n * `403` - Forbidden error with your API key or account\n * `404` - The requested item does not exist\n * `413` - Payload too large\n * `422` - The query or body parameters did not pass validation\n * `429` - Too many requests have been sent with an API key in a given amount of time\n * `500` - An internal server error occurred, please contact support@lob.com\n" object: type: string description: Value is resource type. failure_reason_error: type: object description: Failure error details properties: url: type: string description: Failed URL of asset nullable: true host: type: string description: URL host nullable: true path: type: string description: URL path nullable: true protocol: type: string description: Network protocol nullable: true remediation: type: string description: Instructions on how to resolve the error nullable: true error_type: type: string description: HTTP response status code message or service defined error nullable: true status_code: type: number description: HTTP response status codes if the error is asset related nullable: true status: type: string enum: - processed - rendered - failed description: 'A string describing the PDF render status: * `processed` - the rendering process is currently in progress. * `rendered` - a PDF has been successfully rendered of the mailpiece. * `failed` - one or more issues has caused the rendering process to fail. ' date_modified: type: string format: date-time description: A timestamp in ISO 8601 format of the date the resource was last modified. expected_delivery_date: type: string description: A date in YYYY-MM-DD format of the mailpiece's expected delivery date based on its `send_date`. format: date responses: mailpiece_error: description: Error content: application/json: schema: $ref: '#/components/schemas/error' example: error: code: not_found message: to address not found status_code: 404 self_mailer_deleted: description: Deleted content: application/json: schema: $ref: '#/components/schemas/self_mailer_deletion' example: id: sfm_123456789 deleted: true securitySchemes: basicAuth: type: http scheme: basic x-webhooks: events: post: summary: Events description: Information about an event operationId: event tags: - Events responses: '200': $ref: '#/components/responses/events' tracking_events: post: summary: Tracking Events description: Information about tracking events operationId: tracking_event tags: - Tracking Events responses: '200': $ref: '#/components/responses/tracking_events' x-tagGroups: - name: Overview tags: - Introduction - Authentication - Getting Started - SDKs and Tools - name: Address Book tags: - Addresses - National Change of Address - name: Print and Mail API tags: - Postcards - Self Mailers - Letters - Checks - Snap Packs - Booklets - Bank Accounts - Templates - Template Versions - Template Design - Manage Mail - name: Campaigns API (BETA) tags: - Campaigns - Creatives - Uploads - name: Informed Delivery Campaign API tags: - Informed Delivery Campaign - name: Address Verification API tags: - US Verifications - US Verification Types - US Autocompletions - Reverse Geocode Lookups - Zip Lookups - Identity Validation - Intl Verifications - name: Webhooks tags: - Webhooks - Events - Tracking Events - name: Special Features tags: - Billing Groups - Buckslips - Buckslip Orders - Cards - Card Orders - QR Codes - URL Shortener - name: Appendix tags: - Beta Program - Errors - Rate Limiting - Requests and Responses - Test and Live Environments - Versioning and Changelog